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
|
// 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.
syntax = "proto3";
package options;
option java_package = "com.google.devtools.common.options.proto";
// IMPORTANT NOTE: Changing this proto has specific compatibility requirements.
// ** Waved during the transition phase **
// This enum is not yet depended on externally and none of these constraints
// matter until that flip is switched.
// TODO(bazel-team) Remove the wave of compatibility requirements after the
// transition period is over.
//
// These tags are used for flag filtering. They are consumed by tools that
// process bazel's output, and for this reason must be kept backwards compatible
// until the build horizon has passed.
// - 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.
// - 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.
// - 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.
// These tags should describe the intent and effects of option.
//
// 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 would be mostly useful while debugging, to help identify a
// command line capable of reproducing an error, so the lists of options tagged
// with each EffectTag should be as close to complete and correct as we can
// keep them.
enum OptionEffectTag {
// This option's effect or intent is unknown.
//
// 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. Kept here for completeness and for
// deprecated flags. No new flag should set this tag.
NO_OP = 1;
// Using this option causes blaze 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.
//
// 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;
}
// On top of categorizing options by their intended purpose, these tags should
// identify options that are either not supported or are intended to break old
// behavior.
enum OptionMetadataTag {
// This option triggers an experimental feature with no guarantees of
// functionality
//
// Note: this is separate from UNDOCUMENTED flags, which are flags we don't
// want listed and shouldn't be widely used. Experimental flags should
// probably also be undocumented, but not all undocumented flags should be
// labeled experimental.
EXPERIMENTAL = 0;
// This option triggers a breaking change that is off by default, but will be
// enabled in the next major Bazel version. Use this option to test your
// migration readiness or get early access to the feature.
INCOMPATIBLE_CHANGE = 1;
// This flag is deprecated. It might either no longer have any effect, or
// might no longer be supported.
DEPRECATED = 2;
}
|
