src/main/protobuf/invocation_policy.proto

// 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;

import "src/main/protobuf/strategy_policy.proto";

// 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;

  optional blaze.strategy_policy.StrategyPolicy strategy_policy = 2;
}

// 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 behavior = APPEND 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 behavior = APPEND (see below).
  //
  // 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;

  // Obsolete overridable and append fields.
  reserved 2, 3;

  enum Behavior {
    UNDEFINED = 0;
    // Change the flag value but allow it to be overridden by explicit settings
    // from command line/config expansion/rc files.
    // Matching old flag values: append = false, overridable = true.
    ALLOW_OVERRIDES = 1;
    // Append a new value for a repeatable flag, leave old values and allow
    // further overrides.
    // Matching old flag values: append = true, overridable = false.
    APPEND = 2;
    // Set a final value of the flag. Any overrides provided by the user for
    // this flag will be ignored.
    // Matching old flag values: append = false, overridable = false.
    FINAL_VALUE_IGNORE_OVERRIDES = 3;
  }

  // Defines how invocation policy should interact with user settings for the
  // same flag.
  optional Behavior behavior = 4;
}

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;
  }
}