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 // TODO(bazel-team) - remove the transition-period waive of compatibility requirements. 17 /** 18 * These tags should describe the intent and effects of an option. 19 * 20 * <p>These will be used for filtering noise in long and complex command-lines, to help provide an 21 * overview of which options were likely to have an effect on an issue. This should help reproduce 22 * both working or broken behavior, as we want this to be useful both for debugging and for 23 * avoiding users blindly copying command lines. For this reason, even experimental and undocumented 24 * flags should list their effects. All flags have at least one effect (if not, NO_OP is provided) 25 * so all @Options will require at least one value. 26 * 27 * <p>This file must be kept in sync with the matching proto. The information is duplicated to keep 28 * the proto dependency out of users of this options library. 29 * 30 * <p>IMPORTANT NOTE**: Changing this enum has specific compatibility requirements: 31 * 32 * <p>These tags are used for flag filtering, so are consumed by tools that process bazel's 33 * output, and for this reason must be kept backwards compatible until the build horizon has passed. 34 * 35 * <ul> 36 * <li>To add a new tag, add it here and to all flags it applies to. If you cannot do this in a 37 * single change, mark it as "deprecated" until it has been applied everywhere. Once it can be 38 * relied upon, remove the deprecation mark. 39 * <li>To remove a tag, remove it from all flags and mark it as deprecated for 6 months before 40 * removing it entirely from the list below. 41 * <li>To change the intent of a tag (i.e. to tighten or loosen its definition), make sure that 42 * the new scope doesn't include untagged options or exclude options that still have this tag. 43 * Please try not to do this. Create a new value and deprecate the old one instead, to avoid 44 * confusion. 45 * </ul> 46 * 47 * <p>** Waived during the transition phase : The proto is not yet depended on externally and none 48 * of these constraints are rigid until that switch is flipped. Generally, during the transition 49 * phase while we go through the depot, you can safely assume that the list of categories and tags 50 * is incomplete. If you see a hole, fill it! Please still do make an effort to go through 51 * already-categorized options bases that have options that your new/altered tag would apply to, 52 * file a bug against flag owners or go through them yourself. This is not meant to block you from 53 * adding tags, just to keep the end state sane. 54 */ 55 public enum OptionEffectTag { 56 /** 57 * This option's effect or intent is unknown. 58 * 59 * <p>Please do not use this value for new flags. This is meant to aid transition and for a very 60 * specific set of flags that actually have unknown effect, such as --config and 61 * --all_incompatible_changes, where the effect depends on what other options are triggered. 62 */ 63 UNKNOWN(0), 64 65 /** 66 * This flag has literally no effect. 67 * 68 * <p>Kept here for completeness and for deprecated flags. No new flag should set this tag. 69 */ 70 NO_OP(1), 71 72 /** 73 * Using this option causes Bazel to lose potentially significant incremental state, which may 74 * make this or following builds slower. State could be lost due to a server restart or to 75 * invalidation of a large part of the dependency graph. 76 */ 77 LOSES_INCREMENTAL_STATE(2), 78 79 /** 80 * This option affects the inputs to the command. For example, it might affect Bazel's interaction 81 * with repository versions, or be a meta-option that affects the options set for a given 82 * invocation. 83 * 84 * <p>Yes, all options are technically inputs, but only options that affect inputs other 85 * than itself should be tagged. 86 */ 87 CHANGES_INPUTS(3), 88 89 /** 90 * This option affects bazel's outputs. Which outputs exist and where they go are both relevant 91 * here. This tag is intentionally broad, as many different types of flags will affect the output 92 * of the invocation. 93 */ 94 AFFECTS_OUTPUTS(4), 95 96 /** This option affects the semantics of BUILD or bzl files. */ 97 BUILD_FILE_SEMANTICS(5), 98 99 /** 100 * This option affects settings of Bazel-internal machinery. This tag does not, on its own, mean 101 * that external artifacts are affected, but the route taken to make them might have differed. 102 */ 103 BAZEL_INTERNAL_CONFIGURATION(6), 104 105 /** 106 * This option affects the loading and analysis of dependencies, and the building of the 107 * dependency graph. 108 */ 109 LOADING_AND_ANALYSIS(7), 110 111 /** 112 * This option affects the execution phase. Sandboxing or remote execution related options should 113 * use this category. 114 */ 115 EXECUTION(8), 116 117 /** 118 * This option triggers an optimization that may be machine specific and is not guaranteed to work 119 * on all machines. Depending on what is being optimized for, this could be a tradeoff with other 120 * aspects of performance, such as memory or cpu cost. 121 */ 122 HOST_MACHINE_RESOURCE_OPTIMIZATIONS(9), 123 124 /** This option changes how eagerly a Bazel invocation will exit from a failure. */ 125 EAGERNESS_TO_EXIT(10), 126 127 /** 128 * This option is used for the purposes of monitoring Bazel behavior or performance. The 129 * information collected might have effect on logging output, but should not be relevant for the 130 * majority of Bazel users that aren't also Bazel developers. 131 */ 132 BAZEL_MONITORING(11), 133 134 /** 135 * This option affects Bazel's terminal output, but should not affect its operations. Verbosity 136 * and formatting options should have this tag. 137 */ 138 TERMINAL_OUTPUT(12), 139 140 /** 141 * This option is used to change command line arguments of one or more actions during the build. 142 * 143 * <p>Even though many options implicitly change command line arguments because they change 144 * configured target analysis, this setting is intended for options specifically meant for 145 * for that purpose. 146 */ 147 ACTION_COMMAND_LINES(13), 148 149 /** This option is used to change the testrunner environment of the build. */ 150 TEST_RUNNER(14); 151 152 private final int value; 153 OptionEffectTag(int value)154 OptionEffectTag(int value) { 155 this.value = value; 156 } 157 getValue()158 public int getValue() { 159 return value; 160 } 161 } 162