Adds the command line report protocol.

This will be used by tools to pass Bazel their command lines, and by Bazel to report its command line(s) via the build event stream. See https://bazel.build/designs/2017/07/13/improved-command-line-reporting.html for additional context on why this is useful.

This proto is intentionally vague about certain details of the command line, in order to be accommodating of future changes. However, it needs to be specific enough that it is very clear how a command line would be broken up into the different types of sections.

PiperOrigin-RevId: 168576969

2 files changed, 121 insertions, 0 deletions

diff --git a/src/main/protobuf/BUILD b/src/main/protobuf/BUILD
index 820e5244f4..d20eff5256 100644
--- a/src/main/protobuf/BUILD
+++ b/src/main/protobuf/BUILD
@@ -60,6 +60,25 @@ java_library_srcs(
     deps = [":option_filters_java_proto"],
 )
 
+proto_library(
+    name = "command_line_proto",
+    srcs = ["command_line.proto"],
+    visibility = ["//visibility:private"],
+    deps = [":option_filters_proto"],
+)
+
+java_proto_library(
+    name = "command_line_java_proto",
+    visibility = ["//src:__subpackages__"],
+    deps = [":command_line_proto"],
+)
+
+java_library_srcs(
+    name = "command_line_java_proto_srcs",
+    visibility = ["//visibility:private"],
+    deps = [":command_line_java_proto"],
+)
+
 cc_proto_library(
     name = "worker_protocol_cc_proto",
     deps = [":worker_protocol_proto"],
@@ -91,6 +110,7 @@ filegroup(
 filegroup(
     name = "dist_jars",
     srcs = [s + "_java_proto_srcs" for s in FILES] + [
+        ":command_line_java_proto_srcs",
         ":command_server_java_grpc_srcs",
         ":option_filters_java_proto_srcs",
     ],
diff --git a/src/main/protobuf/command_line.proto b/src/main/protobuf/command_line.proto
new file mode 100644
index 0000000000..dd04ffb674
--- /dev/null
+++ b/src/main/protobuf/command_line.proto
@@ -0,0 +1,101 @@
+// Copyright 2017 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 = "proto3";
+package command_line;
+
+option java_package = "com.google.devtools.build.lib.runtime.proto";
+
+import "src/main/protobuf/option_filters.proto";
+
+// Representation of a Bazel command line.
+message CommandLine {
+  // A title for this command line value, to differentiate it from others.
+  // In particular, a single invocation may wish to report both the literal and
+  // canonical command lines, and this label would be used to differentiate
+  // between both versions. This is a string for flexibility.
+  string label = 1;
+
+  // A Bazel command line is made of distinct parts. For example,
+  //    `bazel --nomaster_bazelrc test --nocache_test_results //foo:aTest`
+  // has the executable "bazel", a startup flag, a command "test", a command
+  // flag, and a test target. There could be many more flags and targets, or
+  // none (`bazel info` for example), but the basic structure is there. The
+  // command line should be broken down into these logical sections here.
+  repeated CommandLineSection sections = 2;
+}
+
+// A section of the Bazel command line.
+message CommandLineSection {
+  // The name of this section, such as "startup_option" or "command".
+  string section_label = 1;
+
+  oneof section_type {
+    // Sections with non-options, such as the list of targets or the command,
+    // should use simple string chunks.
+    ChunkList chunk_list = 2;
+
+    // Startup and command options are lists of options and belong here.
+    OptionList option_list = 3;
+  }
+}
+
+// Wrapper to allow a list of strings in the "oneof" section_type.
+message ChunkList {
+  repeated string chunk = 1;
+}
+
+// Wrapper to allow a list of options in the "oneof" section_type.
+message OptionList {
+  repeated Option option = 1;
+}
+
+// A single command line option.
+//
+// This represents the option itself, but does not take into account the type of
+// option or how the parser interpreted it. If this option is part of a command
+// line that represents the actual input that Bazel received, it would, for
+// example, include expansion flags as they are. However, if this option
+// represents the canonical form of the command line, with the values as Bazel
+// understands them, then the expansion flag, which has no value, would not
+// appear, and the flags it expands to would.
+message Option {
+  // How the option looks with the option and its value combined. Depending on
+  // the purpose of this command line report, this could be the canonical
+  // form, or the way that the flag was set.
+  //
+  // Some examples: this might be `--foo=bar` form, or `--foo bar` with a space;
+  // for boolean flags, `--nobaz` is accepted on top of `--baz=false` and other
+  // negating values, or for a positive value, the unqualified `--baz` form
+  // is also accepted. This could also be a short `-b`, if the flag has an
+  // abbreviated form.
+  string combined_form = 1;
+
+  // The canonical name of the option, without the preceding dashes.
+  string option_name = 2;
+
+  // The value of the flag, or unset for flags that do not take values.
+  // Especially for boolean flags, this should be in canonical form, the
+  // combined_form field above gives room for showing the flag as it was set
+  // if that is preferred.
+  string option_value = 3;
+
+  // This flag's tagged effects. See OptionEffectTag's java documentation for
+  // details.
+  repeated options.OptionEffectTag effect_tags = 4;
+
+  // Metadata about the flag. See OptionMetadataTag's java documentation for
+  // details.
+  repeated options.OptionMetadataTag metadata_tags = 5;
+}