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