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
|
// 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_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 {
// Policies will be applied in order. Later policies will override
// previous policies if they conflict, which is important for flags
// that interact with each other. For example, if there is a flag "--foo"
// which is an expansion flag that expands into "--bar=x --baz=y", and the
// policy list first has a SetValue policy for "set --bar to z", and then has
// a SetDefault policy to set "--foo" to its default value, both --bar and
// --baz will get reset to their default values, overriding the SetValue
// operation. The SetDefault should come before the SetValue.
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" and "no_" prefixes 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 is
// being run. 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.
//
// 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).
//
// 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;
}
message UseDefault {
// Use the default value of the flag, as defined by Bazel (or equivalently, do
// not allow the user to set this flag).
}
message DisallowValues {
// It is an error for the user to use any of these values (that is, the Bazel
// command will fail).
//
// 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;
// If the default value of the flag is a disallowed value, use this
// as the default if the user doesn't specify the flag.
// Similar to doing a SetValue with overridable set to true, but also
// wanting to limit the available values. Note that flags that set
// allowMultiple to true cannot have default values (they default to the
// empty list), which is why this field is optional and not repeated.
optional string new_default_value = 2;
}
message AllowValues {
// It is an error for the user to use any value not in this list.
repeated string allowed_values = 1;
// If the default value of the flag is a not an allowed value, use this
// as the default if the user doesn't specify the flag.
// Similar to doing a SetValue with overridable set to true, but also
// wanting to limit the available values. Note that flags that set
// allowMultiple to true cannot have default values (they default to the
// empty list), which is why this field is optional and not repeated.
optional string new_default_value = 2;
}
|
