1 // Copyright 2017 The Bazel Authors. All rights reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 package com.google.devtools.common.options; 15 16 import com.google.common.collect.ImmutableMap; 17 18 /** 19 * Provides descriptions of the options filters, for use in generated documentation and usage text. 20 */ 21 public class OptionFilterDescriptions { 22 23 /** The order that the categories should be listed in. */ 24 static OptionDocumentationCategory[] documentationOrder = { 25 OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, 26 OptionDocumentationCategory.EXECUTION_STRATEGY, 27 OptionDocumentationCategory.TOOLCHAIN, 28 OptionDocumentationCategory.OUTPUT_SELECTION, 29 OptionDocumentationCategory.OUTPUT_PARAMETERS, 30 OptionDocumentationCategory.INPUT_STRICTNESS, 31 OptionDocumentationCategory.SIGNING, 32 OptionDocumentationCategory.TESTING, 33 OptionDocumentationCategory.QUERY, 34 OptionDocumentationCategory.BUILD_TIME_OPTIMIZATION, 35 OptionDocumentationCategory.LOGGING, 36 OptionDocumentationCategory.GENERIC_INPUTS, 37 OptionDocumentationCategory.UNCATEGORIZED 38 }; 39 40 static ImmutableMap<OptionDocumentationCategory, String> getOptionCategoriesEnumDescription( 41 String productName) { 42 ImmutableMap.Builder<OptionDocumentationCategory, String> optionCategoriesBuilder = 43 ImmutableMap.builder(); 44 optionCategoriesBuilder 45 .put( 46 OptionDocumentationCategory.UNCATEGORIZED, 47 "Miscellaneous options, not otherwise categorized.") 48 .put( // Here for completeness, the help output should not include this option. 49 OptionDocumentationCategory.UNDOCUMENTED, 50 "This feature should not be documented, as it is not meant for general use") 51 .put( 52 OptionDocumentationCategory.BAZEL_CLIENT_OPTIONS, 53 "Options that appear before the command and are parsed by the client") 54 .put( 55 OptionDocumentationCategory.LOGGING, 56 "Options that affect the verbosity, format or location of logging") 57 .put(OptionDocumentationCategory.EXECUTION_STRATEGY, "Options that control build execution") 58 .put( 59 OptionDocumentationCategory.BUILD_TIME_OPTIMIZATION, 60 "Options that trigger optimizations of the build time") 61 .put( 62 OptionDocumentationCategory.OUTPUT_SELECTION, 63 "Options that control the output of the command") 64 .put( 65 OptionDocumentationCategory.OUTPUT_PARAMETERS, 66 "Options that let the user configure the intended output, affecting its value, as " 67 + "opposed to its existence") 68 .put( 69 OptionDocumentationCategory.INPUT_STRICTNESS, 70 "Options that affect how strictly Bazel enforces valid build inputs (rule definitions, " 71 + " flag combinations, etc.)") 72 .put( 73 OptionDocumentationCategory.SIGNING, 74 "Options that affect the signing outputs of a build") 75 .put( 76 OptionDocumentationCategory.TESTING, 77 "Options that govern the behavior of the test environment or test runner") 78 .put( 79 OptionDocumentationCategory.TOOLCHAIN, 80 "Options that configure the toolchain used for action execution") 81 .put(OptionDocumentationCategory.QUERY, "Options relating to query output and semantics") 82 .put( 83 OptionDocumentationCategory.GENERIC_INPUTS, 84 "Options specifying or altering a generic input to a Bazel command that does not fall " 85 + "into other categories."); 86 return optionCategoriesBuilder.build(); 87 } 88 89 public static ImmutableMap<OptionEffectTag, String> getOptionEffectTagDescription( 90 String productName) { 91 ImmutableMap.Builder<OptionEffectTag, String> effectTagDescriptionBuilder = 92 ImmutableMap.builder(); 93 effectTagDescriptionBuilder 94 .put(OptionEffectTag.UNKNOWN, "This option has unknown, or undocumented, effect.") 95 .put(OptionEffectTag.NO_OP, "This option has literally no effect.") 96 .put( 97 OptionEffectTag.LOSES_INCREMENTAL_STATE, 98 "Changing the value of this option can cause significant loss of incremental " 99 + "state, which slows builds. State could be lost due to a server restart or to " 100 + "invalidation of a large part of the dependency graph.") 101 .put( 102 OptionEffectTag.CHANGES_INPUTS, 103 "This option actively changes the inputs that " 104 + productName 105 + " considers for the build, such as filesystem restrictions, repository versions, " 106 + "or other options.") 107 .put( 108 OptionEffectTag.AFFECTS_OUTPUTS, 109 "This option affects " 110 + productName 111 + "'s outputs. This tag is intentionally broad, can include transitive affects, " 112 + "and does not specify the type of output it affects.") 113 .put( 114 OptionEffectTag.BUILD_FILE_SEMANTICS, 115 "This option affects the semantics of BUILD or .bzl files.") 116 .put( 117 OptionEffectTag.BAZEL_INTERNAL_CONFIGURATION, 118 "This option affects settings of " 119 + productName 120 + "-internal machinery. This tag does not, on its own, mean that build artifacts " 121 + "are affected.") 122 .put( 123 OptionEffectTag.LOADING_AND_ANALYSIS, 124 "This option affects the loading and analysis of dependencies, and the building " 125 + "of the dependency graph.") 126 .put( 127 OptionEffectTag.EXECUTION, 128 "This option affects the execution phase, such as sandboxing or remote execution " 129 + "related options.") 130 .put( 131 OptionEffectTag.HOST_MACHINE_RESOURCE_OPTIMIZATIONS, 132 "This option triggers an optimization that may be machine specific and is not " 133 + "guaranteed to work on all machines. The optimization could include a tradeoff " 134 + "with other aspects of performance, such as memory or cpu cost.") 135 .put( 136 OptionEffectTag.EAGERNESS_TO_EXIT, 137 "This option changes how eagerly " 138 + productName 139 + " will exit from a failure, where a choice between continuing despite the " 140 + "failure and ending the invocation exists.") 141 .put( 142 OptionEffectTag.BAZEL_MONITORING, 143 "This option is used to monitor " + productName + "'s behavior and performance.") 144 .put( 145 OptionEffectTag.TERMINAL_OUTPUT, 146 "This option affects " + productName + "'s terminal output.") 147 .put( 148 OptionEffectTag.ACTION_COMMAND_LINES, 149 "This option changes the command line arguments of one or more build actions.") 150 .put( 151 OptionEffectTag.TEST_RUNNER, 152 "This option changes the testrunner environment of the build."); 153 return effectTagDescriptionBuilder.build(); 154 } 155 156 public static ImmutableMap<OptionMetadataTag, String> getOptionMetadataTagDescription( 157 String productName) { 158 ImmutableMap.Builder<OptionMetadataTag, String> effectTagDescriptionBuilder = 159 ImmutableMap.builder(); 160 effectTagDescriptionBuilder 161 .put( 162 OptionMetadataTag.EXPERIMENTAL, 163 "This option triggers an experimental feature with no guarantees of functionality.") 164 .put( 165 OptionMetadataTag.INCOMPATIBLE_CHANGE, 166 "This option triggers a breaking change. Use this option to test your migration " 167 + "readiness or get early access to the new feature") 168 .put( 169 OptionMetadataTag.DEPRECATED, 170 "This option is deprecated. It might be that the feature it affects is deprecated, " 171 + "or that another method of supplying the information is preferred.") 172 .put( 173 OptionMetadataTag.HIDDEN, // Here for completeness, these options are UNDOCUMENTED. 174 "This option should not be used by a user, and should not be logged.") 175 .put( 176 OptionMetadataTag.INTERNAL, // Here for completeness, these options are UNDOCUMENTED. 177 "This option isn't even a option, and should not be logged."); 178 return effectTagDescriptionBuilder.build(); 179 } 180 } 181
