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
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
// Copyright 2015 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 = "proto2";
package blaze.invocation_policy;
// option java_api_version = 2;
option java_package = "com.google.devtools.build.lib.runtime.proto";
// The --invocation_policy flag takes a base64-encoded binary-serialized or text
// formatted InvocationPolicy message.
message InvocationPolicy {
// Order matters.
// After expanding policies on expansion flags or flags with implicit
// requirements, only the final policy on a specific flag will be enforced
// onto the user's command line.
repeated FlagPolicy flag_policies = 1;
}
// A policy for controlling the value of a flag.
message FlagPolicy {
// The name of the flag to enforce this policy on.
//
// Note that this should be the full name of the flag, not the abbreviated
// name of the flag. If the user specifies the abbreviated name of a flag,
// that flag will be matched using its full name.
//
// The "no" prefix will not be parsed, so for boolean flags, use
// the flag's full name and explicitly set it to true or false.
optional string flag_name = 1;
// If set, this flag policy is applied only if one of the given commands or a
// command that inherits from one of the given commands is being run. For
// instance, if "build" is one of the commands here, then this policy will
// apply to any command that inherits from build, such as info, coverage, or
// test. If empty, this flag policy is applied for all commands. This allows
// the policy setter to add all policies to the proto without having to
// determine which Bazel command the user is actually running. Additionally,
// Bazel allows multiple flags to be defined by the same name, and the
// specific flag definition is determined by the command.
repeated string commands = 2;
oneof operation {
SetValue set_value = 3;
UseDefault use_default = 4;
DisallowValues disallow_values = 5;
AllowValues allow_values = 6;
}
}
message SetValue {
// Use this value for the specified flag, overriding any default or user-set
// value (unless append is set to true for repeatable flags).
//
// This field is repeated for repeatable flags. It is an error to set
// multiple values for a flag that is not actually a repeatable flag.
// This requires at least 1 value, if even the empty string.
//
// If the flag allows multiple values, all of its values are replaced with the
// value or values from the policy (i.e., no diffing or merging is performed),
// unless the append field (see below) is set to true.
//
// Note that some flags are tricky. For example, some flags look like boolean
// flags, but are actually Void expansion flags that expand into other flags.
// The Bazel flag parser will accept "--void_flag=false", but because
// the flag is Void, the "=false" is ignored. It can get even trickier, like
// "--novoid_flag" which is also an expansion flag with the type Void whose
// name is explicitly "novoid_flag" and which expands into other flags that
// are the opposite of "--void_flag". For expansion flags, it's best to
// explicitly override the flags they expand into.
//
// Other flags may be differently tricky: A flag could have a converter that
// converts some string to a list of values, but that flag may not itself have
// allowMultiple set to true.
//
// An example is "--test_tag_filters": this flag sets its converter to
// CommaSeparatedOptionListConverter, but does not set allowMultiple to true.
// So "--test_tag_filters=foo,bar" results in ["foo", "bar"], however
// "--test_tag_filters=foo --test_tag_filters=bar" results in just ["bar"]
// since the 2nd value overrides the 1st.
//
// Similarly, "--test_tag_filters=foo,bar --test_tag_filters=baz,qux" results
// in ["baz", "qux"]. For flags like these, the policy should specify
// "foo,bar" instead of separately specifying "foo" and "bar" so that the
// converter is appropriately invoked.
//
// Note that the opposite is not necessarily
// true: for a flag that specifies allowMultiple=true, "--flag=foo,bar"
// may fail to parse or result in an unexpected value.
repeated string flag_value = 1;
// Whether to allow this policy to be overridden by user-specified values.
// When set, if the user specified a value for this flag, use the value
// from the user, otherwise use the value specified in this policy.
optional bool overridable = 2;
// If true, and if the flag named in the policy is a repeatable flag, then
// the values listed in flag_value do not replace all the user-set or default
// values of the flag, but instead append to them. If the flag is not
// repeatable, then this has no effect.
optional bool append = 3;
}
message UseDefault {
// Use the default value of the flag, as defined by Bazel (or equivalently, do
// not allow the user to set this flag).
//
// Note on implementation: UseDefault sets the default by clearing the flag,
// so that when the value is requested and no flag is found, the flag parser
// returns the default. This is mostly relevant for expansion flags: it will
// erase user values in *all* flags that the expansion flag expands to. Only
// use this on expansion flags if this is acceptable behavior. Since the last
// policy wins, later policies on this same flag will still remove the
// expanded UseDefault, so there is a way around, but it's really best not to
// use this on expansion flags at all.
}
message DisallowValues {
// Obsolete new_default_value field.
reserved 2;
// It is an error for the user to use any of these values (that is, the Bazel
// command will fail), unless new_value or use_default is set.
//
// For repeatable flags, if any one of the values in the flag matches a value
// in the list of disallowed values, an error is thrown.
//
// Care must be taken for flags with complicated converters. For example,
// it's possible for a repeated flag to be of type List<List<T>>, so that
// "--foo=a,b --foo=c,d" results in foo=[["a","b"], ["c", "d"]]. In this case,
// it is not possible to disallow just "b", nor will ["b", "a"] match, nor
// will ["b", "c"] (but ["a", "b"] will still match).
repeated string disallowed_values = 1;
oneof replacement_value {
// If set and if the value of the flag is disallowed (including the default
// value of the flag if the user doesn't specify a value), use this value as
// the value of the flag instead of raising an error. This does not apply to
// repeatable flags and is ignored if the flag is a repeatable flag.
string new_value = 3;
// If set and if the value of the flag is disallowed, use the default value
// of the flag instead of raising an error. Unlike new_value, this works for
// repeatable flags, but note that the default value for repeatable flags is
// always empty.
//
// Note that it is an error to disallow the default value of the flag and
// to set use_default, unless the flag is a repeatable flag where the
// default value is always the empty list.
UseDefault use_default = 4;
}
}
message AllowValues {
// Obsolete new_default_value field.
reserved 2;
// It is an error for the user to use any value not in this list, unless
// new_value or use_default is set.
repeated string allowed_values = 1;
oneof replacement_value {
// If set and if the value of the flag is disallowed (including the default
// value of the flag if the user doesn't specify a value), use this value as
// the value of the flag instead of raising an error. This does not apply to
// repeatable flags and is ignored if the flag is a repeatable flag.
string new_value = 3;
// If set and if the value of the flag is disallowed, use the default value
// of the flag instead of raising an error. Unlike new_value, this works for
// repeatable flags, but note that the default value for repeatable flags is
// always empty.
//
// Note that it is an error to disallow the default value of the flag and
// to set use_default, unless the flag is a repeatable flag where the
// default value is always the empty list.
UseDefault use_default = 4;
}
}
|
