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, features, licenses, proto_source_root, restricted_to, 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 ProtoSourcesProvider.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.
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).