Documentation

Edit

Protocol Buffer Rules

proto_lang_toolchain

proto_lang_toolchain(name, blacklisted_protos, command_line, compatible_with, deprecation, distribs, features, licenses, plugin, restricted_to, runtime, tags, testonly, visibility)

Specifies how a LANG_proto_library rule (e.g., java_proto_library) should invoke the proto-compiler. Some LANG_proto_library rules allow specifying which toolchain to use using command-line flags; consult their documentation.

Normally you should not write those kind of rules unless you want to tune your Java compiler.

There's no compiler. The proto-compiler is taken from the proto_library rule we attach to. It is passed as a command-line flag to Bazel. Several features require a proto-compiler to be invoked on the proto_library rule itself. It's beneficial to enforce the compiler that LANG_proto_library uses is the same as the one proto_library does.

Examples

A simple example would be:

proto_lang_toolchain(
    name = "javalite_toolchain",
    command_line = "--$(PLUGIN_OUT)=shared,immutable:$(OUT)",
    plugin = ":javalite_plugin",
    runtime = ":protobuf_lite",
)

Arguments

Attributes
name

Name; required

A unique name for this target.

blacklisted_protos

List of labels; optional

No code will be generated for files in the srcs attribute of blacklisted_protos. This is used for .proto files that are already linked into proto runtimes, such as any.proto.
command_line

String; required

This value will be passed to proto-compiler to generate the code. Only include the parts specific to this code-generator/plugin (e.g., do not include -I parameters)
  • $(OUT) is LANG_proto_library-specific. The rules are expected to define how they interpret this variable. For Java, for example, $(OUT) will be replaced with the src-jar filename to create.
  • $(PLUGIN_out) will be substituted to work with a `--plugin=protoc-gen-PLUGIN` command line.
plugin

Label; optional

If provided, will be made available to the action that calls the proto-compiler, and will be passed to the proto-compiler: --plugin=protoc-gen-PLUGIN=.
runtime

Label; optional

A language-specific library that the generated code is compiled against. The exact behavior is LANG_proto_librar-specific. Java, for example, should compile against the runtime.

proto_library

proto_library(name, deps, srcs, data, compatible_with, deprecation, distribs, exports, features, import_prefix, licenses, proto_source_root, restricted_to, strip_import_prefix, tags, testonly, visibility)

Use proto_library to define libraries of protocol buffers which may be used from multiple languages. A proto_library may be listed in the deps clause of supported rules, such as java_proto_library.

When compiled on the command-line, a proto_library creates a file named foo-descriptor-set.proto.bin, which is the descriptor set for the messages the rule srcs. The file is a serialized FileDescriptorSet, which is described in https://developers.google.com/protocol-buffers/docs/techniques#self-description.

It only contains information about the .proto files directly mentioned by a proto_library rule; the collection of transitive descriptor sets is available through the proto.transitive_descriptor_sets Skylark provider. See documentation in ProtoInfo.java.

Recommended code organization:

  • One proto_library rule per .proto file.
  • A file named foo.proto will be in a rule named foo_proto, which is located in the same package.
  • A [language]_proto_library that wraps a proto_library named foo_proto should be called foo_[language]_proto, and be located in the same package.

Arguments

Attributes
name

Name; required

A unique name for this target.

deps

List of labels; optional

The list of other proto_library rules that the target depends upon. A proto_library may only depend on other proto_library targets. It may not depend on language-specific libraries.
srcs

List of labels; optional

The list of .proto and .protodevel files that are processed to create the target. This is usually a non empty list. One usecase where srcs can be empty is an alias-library. This is a proto_library rule having one or more other proto_library in deps. This pattern can be used to e.g. export a public api under a persistent name.
exports

List of labels; optional

List of proto_library targets that can be referenced via "import public" in the proto source.
import_prefix

String; optional

The prefix to add to the paths of the .proto files in this rule.

When set, the .proto source files in the srcs attribute of this rule are accessible at is the value of this attribute prepended to their repository-relative path.

The prefix in the strip_import_prefix attribute is removed before this prefix is added.

proto_source_root

String; optional

Directory containing .proto files. If set, it must be equal to the package name. If not set, the source root will be the workspace directory (default).
strip_import_prefix

String; optional

The prefix to strip from the paths of the .proto files in this rule.

When set, .proto source files in the srcs attribute of this rule are accessible at their path with this prefix cut off.

If it's a relative path (not starting with a slash), it's taken as a package-relative one. If it's an absolute one, it's understood as a repository-relative path.

The prefix in the import_prefix attribute is added after this prefix is stripped.