1// Copyright 2017 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 = "proto3";
16package command_line;
17
18// option java_api_version = 2;
19option java_package = "com.google.devtools.build.lib.runtime.proto";
20
21import "src/main/protobuf/option_filters.proto";
22
23// Representation of a Bazel command line.
24message CommandLine {
25  // A title for this command line value, to differentiate it from others.
26  // In particular, a single invocation may wish to report both the literal and
27  // canonical command lines, and this label would be used to differentiate
28  // between both versions. This is a string for flexibility.
29  string command_line_label = 1;
30
31  // A Bazel command line is made of distinct parts. For example,
32  //    `bazel --nomaster_bazelrc test --nocache_test_results //foo:aTest`
33  // has the executable "bazel", a startup flag, a command "test", a command
34  // flag, and a test target. There could be many more flags and targets, or
35  // none (`bazel info` for example), but the basic structure is there. The
36  // command line should be broken down into these logical sections here.
37  repeated CommandLineSection sections = 2;
38}
39
40// A section of the Bazel command line.
41message CommandLineSection {
42  // The name of this section, such as "startup_option" or "command".
43  string section_label = 1;
44
45  oneof section_type {
46    // Sections with non-options, such as the list of targets or the command,
47    // should use simple string chunks.
48    ChunkList chunk_list = 2;
49
50    // Startup and command options are lists of options and belong here.
51    OptionList option_list = 3;
52  }
53}
54
55// Wrapper to allow a list of strings in the "oneof" section_type.
56message ChunkList {
57  repeated string chunk = 1;
58}
59
60// Wrapper to allow a list of options in the "oneof" section_type.
61message OptionList {
62  repeated Option option = 1;
63}
64
65// A single command line option.
66//
67// This represents the option itself, but does not take into account the type of
68// option or how the parser interpreted it. If this option is part of a command
69// line that represents the actual input that Bazel received, it would, for
70// example, include expansion flags as they are. However, if this option
71// represents the canonical form of the command line, with the values as Bazel
72// understands them, then the expansion flag, which has no value, would not
73// appear, and the flags it expands to would.
74message Option {
75  // How the option looks with the option and its value combined. Depending on
76  // the purpose of this command line report, this could be the canonical
77  // form, or the way that the flag was set.
78  //
79  // Some examples: this might be `--foo=bar` form, or `--foo bar` with a space;
80  // for boolean flags, `--nobaz` is accepted on top of `--baz=false` and other
81  // negating values, or for a positive value, the unqualified `--baz` form
82  // is also accepted. This could also be a short `-b`, if the flag has an
83  // abbreviated form.
84  string combined_form = 1;
85
86  // The canonical name of the option, without the preceding dashes.
87  string option_name = 2;
88
89  // The value of the flag, or unset for flags that do not take values.
90  // Especially for boolean flags, this should be in canonical form, the
91  // combined_form field above gives room for showing the flag as it was set
92  // if that is preferred.
93  string option_value = 3;
94
95  // This flag's tagged effects. See OptionEffectTag's java documentation for
96  // details.
97  repeated options.OptionEffectTag effect_tags = 4;
98
99  // Metadata about the flag. See OptionMetadataTag's java documentation for
100  // details.
101  repeated options.OptionMetadataTag metadata_tags = 5;
102}
103