src/main/protobuf/invocation_policy.proto

// Copyright 2015 Google Inc. 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;
}