1// Copyright 2015 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
15syntax = "proto2";
16package blaze.invocation_policy;
17
18// option java_api_version = 2;
19option java_package = "com.google.devtools.build.lib.runtime.proto";
20
21// The --invocation_policy flag takes a base64-encoded binary-serialized or text
22// formatted InvocationPolicy message.
23message InvocationPolicy {
24  // Order matters.
25  // After expanding policies on expansion flags or flags with implicit
26  // requirements, only the final policy on a specific flag will be enforced
27  // onto the user's command line.
28  repeated FlagPolicy flag_policies = 1;
29}
30
31// A policy for controlling the value of a flag.
32message FlagPolicy {
33  // The name of the flag to enforce this policy on.
34  //
35  // Note that this should be the full name of the flag, not the abbreviated
36  // name of the flag. If the user specifies the abbreviated name of a flag,
37  // that flag will be matched using its full name.
38  //
39  // The "no" prefix will not be parsed, so for boolean flags, use
40  // the flag's full name and explicitly set it to true or false.
41  optional string flag_name = 1;
42
43  // If set, this flag policy is applied only if one of the given commands or a
44  // command that inherits from one of the given commands is being run. For
45  // instance, if "build" is one of the commands here, then this policy will
46  // apply to any command that inherits from build, such as info, coverage, or
47  // test. If empty, this flag policy is applied for all commands. This allows
48  // the policy setter to add all policies to the proto without having to
49  // determine which Bazel command the user is actually running. Additionally,
50  // Bazel allows multiple flags to be defined by the same name, and the
51  // specific flag definition is determined by the command.
52  repeated string commands = 2;
53
54  oneof operation {
55    SetValue set_value = 3;
56    UseDefault use_default = 4;
57    DisallowValues disallow_values = 5;
58    AllowValues allow_values = 6;
59  }
60}
61
62message SetValue {
63  // Use this value for the specified flag, overriding any default or user-set
64  // value (unless behavior = APPEND for repeatable flags).
65  //
66  // This field is repeated for repeatable flags. It is an error to set
67  // multiple values for a flag that is not actually a repeatable flag.
68  // This requires at least 1 value, if even the empty string.
69  //
70  // If the flag allows multiple values, all of its values are replaced with the
71  // value or values from the policy (i.e., no diffing or merging is performed),
72  // unless behavior = APPEND (see below).
73  //
74  // Note that some flags are tricky. For example, some flags look like boolean
75  // flags, but are actually Void expansion flags that expand into other flags.
76  // The Bazel flag parser will accept "--void_flag=false", but because
77  // the flag is Void, the "=false" is ignored. It can get even trickier, like
78  // "--novoid_flag" which is also an expansion flag with the type Void whose
79  // name is explicitly "novoid_flag" and which expands into other flags that
80  // are the opposite of "--void_flag". For expansion flags, it's best to
81  // explicitly override the flags they expand into.
82  //
83  // Other flags may be differently tricky: A flag could have a converter that
84  // converts some string to a list of values, but that flag may not itself have
85  // allowMultiple set to true.
86  //
87  // An example is "--test_tag_filters": this flag sets its converter to
88  // CommaSeparatedOptionListConverter, but does not set allowMultiple to true.
89  // So "--test_tag_filters=foo,bar" results in ["foo", "bar"], however
90  // "--test_tag_filters=foo --test_tag_filters=bar" results in just ["bar"]
91  // since the 2nd value overrides the 1st.
92  //
93  // Similarly, "--test_tag_filters=foo,bar --test_tag_filters=baz,qux" results
94  // in ["baz", "qux"]. For flags like these, the policy should specify
95  // "foo,bar" instead of separately specifying "foo" and "bar" so that the
96  // converter is appropriately invoked.
97  //
98  // Note that the opposite is not necessarily
99  // true: for a flag that specifies allowMultiple=true, "--flag=foo,bar"
100  // may fail to parse or result in an unexpected value.
101  repeated string flag_value = 1;
102
103  // Obsolete overridable and append fields.
104  reserved 2, 3;
105
106  enum Behavior {
107    UNDEFINED = 0;
108    // Change the flag value but allow it to be overridden by explicit settings
109    // from command line/config expansion/rc files.
110    // Matching old flag values: append = false, overridable = true.
111    ALLOW_OVERRIDES = 1;
112    // Append a new value for a repeatable flag, leave old values and allow
113    // further overrides.
114    // Matching old flag values: append = true, overridable = false.
115    APPEND = 2;
116    // Set a final value of the flag. Any overrides provided by the user for
117    // this flag will be ignored.
118    // Matching old flag values: append = false, overridable = false.
119    FINAL_VALUE_IGNORE_OVERRIDES = 3;
120  }
121
122  // Defines how invocation policy should interact with user settings for the
123  // same flag.
124  optional Behavior behavior = 4;
125}
126
127message UseDefault {
128  // Use the default value of the flag, as defined by Bazel (or equivalently, do
129  // not allow the user to set this flag).
130  //
131  // Note on implementation: UseDefault sets the default by clearing the flag,
132  // so that when the value is requested and no flag is found, the flag parser
133  // returns the default. This is mostly relevant for expansion flags: it will
134  // erase user values in *all* flags that the expansion flag expands to. Only
135  // use this on expansion flags if this is acceptable behavior. Since the last
136  // policy wins, later policies on this same flag will still remove the
137  // expanded UseDefault, so there is a way around, but it's really best not to
138  // use this on expansion flags at all.
139}
140
141message DisallowValues {
142  // Obsolete new_default_value field.
143  reserved 2;
144
145  // It is an error for the user to use any of these values (that is, the Bazel
146  // command will fail), unless new_value or use_default is set.
147  //
148  // For repeatable flags, if any one of the values in the flag matches a value
149  // in the list of disallowed values, an error is thrown.
150  //
151  // Care must be taken for flags with complicated converters. For example,
152  // it's possible for a repeated flag to be of type List<List<T>>, so that
153  // "--foo=a,b --foo=c,d" results in foo=[["a","b"], ["c", "d"]]. In this case,
154  // it is not possible to disallow just "b", nor will ["b", "a"] match, nor
155  // will ["b", "c"] (but ["a", "b"] will still match).
156  repeated string disallowed_values = 1;
157
158  oneof replacement_value {
159    // If set and if the value of the flag is disallowed (including the default
160    // value of the flag if the user doesn't specify a value), use this value as
161    // the value of the flag instead of raising an error. This does not apply to
162    // repeatable flags and is ignored if the flag is a repeatable flag.
163    string new_value = 3;
164
165    // If set and if the value of the flag is disallowed, use the default value
166    // of the flag instead of raising an error. Unlike new_value, this works for
167    // repeatable flags, but note that the default value for repeatable flags is
168    // always empty.
169    //
170    // Note that it is an error to disallow the default value of the flag and
171    // to set use_default, unless the flag is a repeatable flag where the
172    // default value is always the empty list.
173    UseDefault use_default = 4;
174  }
175}
176
177message AllowValues {
178  // Obsolete new_default_value field.
179  reserved 2;
180
181  // It is an error for the user to use any value not in this list, unless
182  // new_value or use_default is set.
183  repeated string allowed_values = 1;
184
185  oneof replacement_value {
186    // If set and if the value of the flag is disallowed (including the default
187    // value of the flag if the user doesn't specify a value), use this value as
188    // the value of the flag instead of raising an error. This does not apply to
189    // repeatable flags and is ignored if the flag is a repeatable flag.
190    string new_value = 3;
191
192    // If set and if the value of the flag is disallowed, use the default value
193    // of the flag instead of raising an error. Unlike new_value, this works for
194    // repeatable flags, but note that the default value for repeatable flags is
195    // always empty.
196    //
197    // Note that it is an error to disallow the default value of the flag and
198    // to set use_default, unless the flag is a repeatable flag where the
199    // default value is always the empty list.
200    UseDefault use_default = 4;
201  }
202}
203