path: root/src/main/protobuf/build.proto

// Copyright 2014 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.
//
// This file contains the protocol buffer representation of a build
// file or 'blaze query --output=proto' call.

syntax = "proto2";

package blaze_query;


option java_package = "com.google.devtools.build.lib.query2.proto.proto2api";
option java_generate_equals_and_hash = true;

message License {
  repeated string license_type = 1;
  repeated string exception = 2;
}

message StringDictEntry {
  required string key = 1;
  required string value = 2;
}

message StringDictUnaryEntry {
  required string key = 1;
  required string value = 2;
}

message LabelListDictEntry {
  required string key = 1;
  repeated string value = 2;
}

message StringListDictEntry {
  required string key = 1;
  repeated string value = 2;
}

// Represents an entry attribute of a Fileset rule in a build file.
message FilesetEntry {
  // Indicates what to do when a source file is actually a symlink.
  enum SymlinkBehavior {
    COPY = 1;
    DEREFERENCE = 2;
  }

  // The label pointing to the source target where files are copied from.
  required string source = 1;

  // The relative path within the fileset rule where files will be mapped.
  required string destination_directory = 2;

  // Whether the files= attribute was specified. This is necessary because
  // no files= attribute and files=[] mean different things.
  optional bool files_present = 7;

  // A list of file labels to include from the source directory.
  repeated string file = 3;

  // If this is a fileset entry representing files within the rule
  // package, this lists relative paths to files that should be excluded from
  // the set.  This cannot contain values if 'file' also has values.
  repeated string exclude = 4;

  // This field is optional because there will be some time when the new
  // PB is used by tools depending on blaze query, but the new blaze version
  // is not yet released.
  // TODO(bazel-team): Make this field required once a version of Blaze is
  // released that outputs this field.
  optional SymlinkBehavior symlink_behavior = 5 [ default=COPY ];

  // The prefix to strip from the path of the files in this FilesetEntry. Note
  // that no value and the empty string as the value mean different things here.
  optional string strip_prefix = 6;
}

// A rule attribute.  Each attribute must have a type and can only have one of
// the various value fields populated.  By checking the type, the appropriate
// value can be extracted - see the comments on each type for the associated
// value.  The order of lists comes from the blaze parsing and if an attribute
// is of a list type, the associated list should never be empty.
message Attribute {
  // Indicates the type of attribute.
  enum Discriminator {
    INTEGER = 1;             // int_value
    STRING = 2;              // string_value
    LABEL = 3;               // string_value
    OUTPUT = 4;              // string_value
    STRING_LIST = 5;         // string_list_value
    LABEL_LIST = 6;          // string_list_value
    OUTPUT_LIST = 7;         // string_list_value
    DISTRIBUTION_SET = 8;    // string_list_value - order is unimportant
    LICENSE = 9;             // license
    STRING_DICT = 10;        // string_dict_value
    FILESET_ENTRY_LIST = 11; // fileset_list_value
    LABEL_LIST_DICT = 12;    // label_list_dict_value
    STRING_LIST_DICT = 13;   // string_list_dict_value
    BOOLEAN = 14;            // int, bool and string value
    TRISTATE = 15;           // tristate, int and string value
    INTEGER_LIST = 16;       // int_list_value
    STRING_DICT_UNARY = 17;  // string_dict_unary_value
    UNKNOWN = 18;            // unknown type, use only for build extensions
  }

  // Values for the TriState field type.
  enum Tristate {
    NO = 0;
    YES = 1;
    AUTO = 2;
  }

  // The name of the attribute
  required string name = 1;

  // The location of the target in the BUILD file in a machine-parseable form.
  optional Location parseable_location = 12;

  // Whether the attribute was explicitly specified
  optional bool explicitly_specified = 13;

  // The type of attribute.  This message is used for all of the different
  // attribute types so the discriminator helps for figuring out what is
  // stored in the message.
  required Discriminator type = 2;

  // If this attribute has an integer value this will be populated.
  // Boolean and TriState also use this field as [0,1] and [-1,0,1]
  // for [false, true] and [auto, no, yes] respectively.
  // Null-valued attributes will *not* set this value.
  optional int32 int_value = 3;

  // If the attribute has a string value this will be populated.  Label and
  // path attributes use this field as the value even though the type may
  // be LABEL or something else other than STRING.
  // Null-valued attributes will *not* set this value.
  optional string string_value = 5;

  // If the attribute has a boolean value this will be populated.
  // Null-valued attributes will *not* set this value.
  optional bool boolean_value = 14;

  // If the attribute is a Tristate value, this will be populated.
  // Null-valued attributes will *not* set this value.
  optional Tristate tristate_value = 15;

  // The value of the attribute has a list of string values (label and path
  // note from STRING applies here as well).
  repeated string string_list_value = 6;

  // If this is a license attribute, the license information is stored here.
  // Null-valued attributes will *not* set this value.
  optional License license = 7;

  // If this is a string dict, each entry will be stored here.
  repeated StringDictEntry string_dict_value = 8;

  // If the attribute is part of a Fileset, the fileset entries are stored in
  // this field.
  repeated FilesetEntry fileset_list_value = 9;

  // If this is a label list dict, each entry will be stored here.
  repeated LabelListDictEntry label_list_dict_value = 10;

  // If this is a string list dict, each entry will be stored here.
  repeated StringListDictEntry string_list_dict_value = 11;

  // The glob criteria. This is non-empty if
  // 1. This attribute is a list of strings or labels
  // 2. It contained a glob() expression
  repeated GlobCriteria glob_criteria = 16;

  // The value of the attribute has a list of int32 values
  repeated int32 int_list_value = 17;

  // If this is a string dict unary, each entry will be stored here.
  repeated StringDictUnaryEntry string_dict_unary_value = 18;
}

// A rule from a BUILD file (e.g., cc_library, java_binary).  The rule class
// is the actual name of the rule (e.g., cc_library) and the name is the full
// label of the rule (e.g., //foo/bar:baz).
message Rule {
  // The name of the rule
  required string name = 1;

  // The rule class (e.g., java_library)
  required string rule_class = 2;

  // The BUILD file and line number of the rule.
  optional string location = 3;

  // All of the attributes that describe the rule.
  repeated Attribute attribute = 4;

  // All of the inputs to the rule.  These are predecessors in the dependency
  // graph.  A rule_input for a rule should always be described as a
  // source_file in some package (either the rule's package or some other one).
  repeated string rule_input = 5;

  // All of the outputs of the rule.  These are the successors in the
  // dependency graph.
  repeated string rule_output = 6;

  // The set of all default settings affecting this rule. The name of a default
  // setting is "<setting type>_<setting name>". There currently defined setting
  // types are:
  //
  // - 'blaze': settings implemented in Blaze itself
  repeated string default_setting = 7;

  // The location of the target in the BUILD file in a machine-parseable form.
  optional Location parseable_location = 8;
}

// Summary of all transitive dependencies of 'rule,' where each dependent
// rule is included only once in the 'dependency' field.  Gives complete
// information to analyze the single build target labeled rule.name,
// including optional location of target in BUILD file.
message RuleSummary {
  required Rule rule = 1;
  repeated Rule dependency = 2;
  optional string location = 3;
}

// A package group. Aside from the name, it contains the list of packages
// present in the group (as specified in the BUILD file).
message PackageGroup {
  // The name of the package group
  required string name = 1;

  // The list of packages as specified in the BUILD file. Currently this is
  // only a list of packages, but some time in the future, there might be
  // some type of wildcard mechanism.
  repeated string contained_package = 2;

  // The list of sub package groups included in this one.
  repeated string included_package_group = 3;

  // The location of the target in the BUILD file in a machine-parseable form.
  optional Location parseable_location = 4;
}

// An environment group.
message EnvironmentGroup {
  // The name of the environment group.
  required string name = 1;

  // The environments that belong to this group (as labels).
  repeated string environment = 2;

  // The member environments that rules implicitly support if not otherwise
  // specified.
  repeated string default = 3;
}

// A file that is an input into the build system.
// Next-Id: 8
message SourceFile {
  // The name of the source file (a label).
  required string name = 1;

  // The location of the source file.  This is a path with line numbers, not
  // a label in the build system.
  optional string location = 2;

  // The location of the corresponding label in the BUILD file in a
  // machine-parseable form.
  optional Location parseable_location = 7;

  // Labels of files that are transitively subincluded in this BUILD file. This
  // is present only when the SourceFile represents a BUILD file that
  // subincludes other files. The subincluded file can be either a Python
  // preprocessed build extension or a Skylark file.
  repeated string subinclude = 3;

  // Labels of package groups that are mentioned in the visibility declaration
  // for this source file.
  repeated string package_group = 4;

  // Labels mentioned in the visibility declaration (including :__pkg__ and
  // //visibility: ones)
  repeated string visibility_label = 5;

  // The package-level features enabled for this package. Only present if the
  // SourceFile represents a BUILD file.
  repeated string feature = 6;

  // License attribute for the file.
  optional License license = 8;
}

// A file that is the output of a build rule.
message GeneratedFile {
  // The name of the generated file (a label).
  required string name = 1;

  // The label of the target that generates the file.
  required string generating_rule = 2;

  // The path of the output file (not a label).
  optional string location = 3;
}

// A target from a blaze query execution.  Similar to the Attribute message,
// the Discriminator is used to determine which field contains information.
// For any given type, only one of these can be populated in a single Target.
message Target {
  enum Discriminator {
    RULE = 1;
    SOURCE_FILE = 2;
    GENERATED_FILE = 3;
    PACKAGE_GROUP = 4;
    ENVIRONMENT_GROUP = 5;
  }

  // The type of target contained in the message.
  required Discriminator type = 1;

  // If this target represents a rule, the rule is stored here.
  optional Rule rule = 2;

  // A file that is not generated by the build system (version controlled
  // or created by the test harness).
  optional SourceFile source_file = 3;

  // A generated file that is the output of a rule.
  optional GeneratedFile generated_file = 4;

  // A package group.
  optional PackageGroup package_group = 5;

  // An environment group.
  optional EnvironmentGroup environment_group = 6;
}

// Used to represent a series of Targets as a series of messages. Preferred
// over repeated fields when the number of targets being serialized may result
// in creating a serialized protocol buffer that is larger than the default
// protocol buffer deserialization limit.
message TargetOrTerminator {
  // Is this the last message in the series?
  optional bool is_terminator = 1 [default = false];

  // The Target encoded in this element. Should be set iff is_terminator is
  // false.
  optional Target target = 2;
}

// Container for all of the blaze query results.
message QueryResult {
  // All of the targets returned by the blaze query.
  repeated Target target = 1;
}

////////////////////////////////////////////////////////////////////////////
// Messages dealing with querying the BUILD language itself. For now, this is
// quite simplistic: Blaze can only tell the names of the rule classes, their
// attributes with their type.

// Information about allowed rule classes for a specific attribute of a rule.
message AllowedRuleClassInfo {
  enum AllowedRuleClasses {
    ANY = 1;  // Any rule is allowed to be in this attribute
    SPECIFIED = 2;  // Only the explicitly listed rules are allowed
  }

  required AllowedRuleClasses policy = 1;

  // Rule class names of rules allowed in this attribute, e.g "cc_library",
  // "py_binary". Only present if the allowed_rule_classes field is set to
  // SPECIFIED.
  repeated string allowed_rule_class = 2;
}

// This message represents a single attribute of a single rule.
message AttributeDefinition {

  // Rule name, e.g. "cc_library"
  required string name = 1;
  required Attribute.Discriminator type = 2;
  required bool mandatory = 3;

  // Only present for attributes of type LABEL and LABEL_LIST.
  optional AllowedRuleClassInfo allowed_rule_classes = 4;

  optional string documentation = 5;
}

message RuleDefinition {
  required string name = 1;
  // Only contains documented attributes
  repeated AttributeDefinition attribute = 2;
  optional string documentation = 3;
  // Only for build extensions: label to file that defines the extension
  optional string label = 4;
}

message BuildLanguage {
  // Only contains documented rule definitions
  repeated RuleDefinition rule = 1;
}

message Location {
  optional int32 start_offset = 1;
  optional int32 start_line = 2;
  optional int32 start_column = 3;
  optional int32 end_offset = 4;
  optional int32 end_line = 5;
  optional int32 end_column = 6;
}

message MakeVarBinding {
  required string value = 1;
  required string platform_set_regexp = 2;
}

message MakeVar {
  required string name = 1;
  repeated MakeVarBinding binding = 2;
}

message GlobCriteria {
  // List of includes (or items if this criteria did not come from a glob)
  repeated string include = 1;

  // List of exclude expressions
  repeated string exclude = 2;

  // Whether this message came from a glob
  optional bool glob = 3;
}

message Event {
  enum EventKind {
    ERROR = 1;
    WARNING = 2;
    INFO = 3;
    PROGRESS = 4;
  }

  required EventKind kind = 1;
  optional Location location = 2;
  optional string message = 3;
}

message Package {
  enum State {
    PRESENT = 1;    // The package is present and has changed at this CL
    TOMBSTONE = 2;  // The package got deleted at this CL
    UNKNOWN = 3;    // The database does not contain enough information to know
  }

  required string name = 1;
  optional string repository = 2;
  optional string build_file_path = 3;

  // Default values
  repeated string default_visibility_label = 1001;
  optional bool default_obsolete = 1002;
  optional bool default_testonly = 1003;
  optional string default_deprecation = 1004;
  optional string default_strict_java_deps = 1005;
  repeated string default_copt = 1006;
  optional string default_hdrs_check = 1007;
  optional License default_license = 1008;
  repeated string default_distrib = 1009;
  optional bool default_visibility_set = 1010;

  // Package-level data
  repeated string default_setting = 2002;
  repeated string subinclude_label = 2003;
  repeated MakeVar make_variable = 2004;
  repeated string file_system_dep = 2005;
  optional bool depends_on_external_files = 2006;
  optional bool dependencies_recorded = 2007;
  optional bool contains_errors = 2008;
  optional bool contains_temporary_errors = 2009;
  repeated string skylark_label = 2010;

  // Targets
  repeated SourceFile source_file = 3001;
  repeated PackageGroup package_group = 3002;
  repeated Rule rule = 3003;
  repeated EnvironmentGroup environment_group = 3004;

  // Metadata
  // Reason why the package could not be serialized.
  optional string failure_reason = 4001;
  optional State state = 4002;
  repeated Event event = 4003;
}