ContextQMD
Back to Bazel

Protocol Buffer

docs/versions/7.2.0/reference/be/protocol-buffer.mdx

9.1.016.2 KB
Original Source
<html devsite> <head> <meta name="project_path" value="/_project.yaml"> <meta name="book_path" value="/versions/7.2.0/_book.yaml"> </head> <body> <!-- This document is synchronized with Bazel releases. To edit, submit changes to the Bazel source code. --> <!-- Generated by //src/main/java/com/google/devtools/build/docgen:build-encyclopedia.zip --> <html> <body> <h1 class="page-title">Protocol Buffer Rules</h1>

{% dynamic setvar source_file "src/main/java/com/google/devtools/build/docgen/templates/be/rules.vm" %} {% dynamic setvar version "7.2.0" %} {% dynamic setvar original_path "/reference/be/protocol-buffer" %} {% include "_buttons.html" %}

<h2>Rules</h2> <ul> <li> <a href="#proto_lang_toolchain"> proto_lang_toolchain </a> </li> <li> <a href="#proto_library"> proto_library </a> </li> </ul> <h2 id="proto_lang_toolchain"> proto_lang_toolchain </h2> <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/proto/ProtoLangToolchainRule.java" target="_blank"> View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> </a> <pre class="rule-signature">proto_lang_toolchain(<a href="#proto_lang_toolchain.name">name</a>, <a href="#proto_lang_toolchain.blacklisted_protos">blacklisted_protos</a>, <a href="#proto_lang_toolchain.command_line">command_line</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="common-definitions.html#common.features">features</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="#proto_lang_toolchain.mnemonic">mnemonic</a>, <a href="#proto_lang_toolchain.output_files">output_files</a>, <a href="#proto_lang_toolchain.plugin">plugin</a>, <a href="#proto_lang_toolchain.plugin_format_flag">plugin_format_flag</a>, <a href="#proto_lang_toolchain.progress_message">progress_message</a>, <a href="#proto_lang_toolchain.proto_compiler">proto_compiler</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#proto_lang_toolchain.runtime">runtime</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> <p>If using Bazel, please load the rule from <a href="https://github.com/bazelbuild/rules_proto"> https://github.com/bazelbuild/rules_proto</a>. </p> <p> Specifies how a LANG_proto_library rule (e.g., <code>java_proto_library</code>) should invoke the proto-compiler. Some LANG_proto_library rules allow specifying which toolchain to use using command-line flags; consult their documentation. </p> <p>Normally you should not write those kind of rules unless you want to tune your Java compiler.</p> <p> 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 Blaze. 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 <code>proto_library</code> does. </p> <h4>Examples</h4> <p>A simple example would be: </p> <pre class="code"> proto_lang_toolchain( name = "javalite_toolchain", command_line = "--javalite_out=shared,immutable:$(OUT)", plugin = ":javalite_plugin", runtime = ":protobuf_lite", ) </pre> <h3 id="proto_lang_toolchain_args">Arguments</h3> <table class="table table-condensed table-bordered table-params"> <colgroup> <col class="col-param" /> <col class="param-description" /> </colgroup> <thead> <tr> <th colspan="2">Attributes</th> </tr> </thead> <tbody> <tr> <td id="proto_lang_toolchain.name"><code>name</code></td> <td> <p><a href="/versions/7.2.0/concepts/labels#target-names">Name</a>; required</p> <p>A unique name for this target.</p> 
    </td>
  </tr>
            <tr>
    <td id="proto_lang_toolchain.blacklisted_protos">
      <code>blacklisted_protos</code>
    </td>
    <td>
                <p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; default is <code>[]</code></p>
                        No code will be generated for files in the <code>srcs</code> attribute of
    <code>blacklisted_protos</code>.
    This is used for .proto files that are already linked into proto runtimes, such as
    <code>any.proto</code>.

    </td>
  </tr>
                  <tr>
    <td id="proto_lang_toolchain.command_line">
      <code>command_line</code>
    </td>
    <td>
                <p>String; required</p>
                        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)
    <ul>
      <li><code>$(OUT)</code> 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.</li>
    </ul>

    </td>
  </tr>
                                                                                        <tr>
    <td id="proto_lang_toolchain.mnemonic">
      <code>mnemonic</code>
    </td>
    <td>
                <p>String; default is <code>"GenProto"</code></p>
                        This value will be set as the mnemonic on protoc action.

    </td>
  </tr>
                  <tr>
    <td id="proto_lang_toolchain.output_files">
      <code>output_files</code>
    </td>
    <td>
                <p>String; default is <code>"legacy"</code></p>
                        Controls how <code>$(OUT)</code> in <code>command_line</code> is formatted, either by
    a path to a single file or output directory in case of multiple files.
    Possible values are: "single", "multiple".

    </td>
  </tr>
                  <tr>
    <td id="proto_lang_toolchain.plugin">
      <code>plugin</code>
    </td>
    <td>
                <p><a href="/versions/7.2.0/concepts/labels">Label</a>; default is <code>None</code></p>
                        If provided, will be made available to the action that calls the proto-compiler, and will be
    passed to the proto-compiler:
    <code>--plugin=protoc-gen-PLUGIN=&lt;executable&gt;.</code>

    </td>
  </tr>
                  <tr>
    <td id="proto_lang_toolchain.plugin_format_flag">
      <code>plugin_format_flag</code>
    </td>
    <td>
                <p>String; default is <code>""</code></p>
                        If provided, this value will be passed to proto-compiler to use the plugin. The value must
    contain a single %s which is replaced with plugin executable.
    <code>--plugin=protoc-gen-PLUGIN=&lt;executable&gt;.</code>

    </td>
  </tr>
                  <tr>
    <td id="proto_lang_toolchain.progress_message">
      <code>progress_message</code>
    </td>
    <td>
                <p>String; default is <code>"Generating proto_library %{label}"</code></p>
                        This value will be set as the progress message on protoc action.

    </td>
  </tr>
                  <tr>
    <td id="proto_lang_toolchain.proto_compiler">
      <code>proto_compiler</code>
    </td>
    <td>
                <p><a href="/versions/7.2.0/concepts/labels">Label</a>; default is <code>None</code></p>
                        The proto compiler executable.
    If provided, this target will be used as a proto-compiler to generate the code.

    </td>
  </tr>
                            <tr>
    <td id="proto_lang_toolchain.runtime">
      <code>runtime</code>
    </td>
    <td>
                <p><a href="/versions/7.2.0/concepts/labels">Label</a>; default is <code>None</code></p>
                        A language-specific library that the generated code is compiled against.
    The exact behavior is LANG_proto_library-specific.
    Java, for example, should compile against the runtime.

    </td>
  </tr>
                                                  </tbody>
</table> <h2 id="proto_library"> proto_library </h2> <a class="button button-with-icon" href="https://github.com/bazelbuild/bazel/blob/master/src/main/java/com/google/devtools/build/lib/rules/proto/BazelProtoLibraryRule.java" target="_blank"> View rule source<span class="material-icons icon-after" aria-hidden="true">open_in_new</span> </a> <pre class="rule-signature">proto_library(<a href="#proto_library.name">name</a>, <a href="#proto_library.deps">deps</a>, <a href="#proto_library.srcs">srcs</a>, <a href="common-definitions.html#typical.data">data</a>, <a href="#proto_library.allow_exports">allow_exports</a>, <a href="common-definitions.html#common.compatible_with">compatible_with</a>, <a href="common-definitions.html#common.deprecation">deprecation</a>, <a href="common-definitions.html#common.distribs">distribs</a>, <a href="common-definitions.html#common.exec_compatible_with">exec_compatible_with</a>, <a href="common-definitions.html#common.exec_properties">exec_properties</a>, <a href="#proto_library.exports">exports</a>, <a href="common-definitions.html#common.features">features</a>, <a href="#proto_library.import_prefix">import_prefix</a>, <a href="common-definitions.html#typical.licenses">licenses</a>, <a href="common-definitions.html#common.restricted_to">restricted_to</a>, <a href="#proto_library.strip_import_prefix">strip_import_prefix</a>, <a href="common-definitions.html#common.tags">tags</a>, <a href="common-definitions.html#common.target_compatible_with">target_compatible_with</a>, <a href="common-definitions.html#common.testonly">testonly</a>, <a href="common-definitions.html#common.visibility">visibility</a>)</pre> <p>Deprecated. Please use <a href="https://github.com/bazelbuild/rules_proto"> https://github.com/bazelbuild/rules_proto</a> instead. </p> <p>Use <code>proto_library</code> to define libraries of protocol buffers which may be used from multiple languages. A <code>proto_library</code> may be listed in the <code>deps</code> clause of supported rules, such as <code>java_proto_library</code>. </p> <p>When compiled on the command-line, a <code>proto_library</code> creates a file named <code>foo-descriptor-set.proto.bin</code>, which is the descriptor set for the messages the rule srcs. The file is a serialized <code>FileDescriptorSet</code>, which is described in <a href="https://developers.google.com/protocol-buffers/docs/techniques#self-description"> https://developers.google.com/protocol-buffers/docs/techniques#self-description</a>. </p> <p>It only contains information about the <code>.proto</code> files directly mentioned by a <code>proto_library</code> rule; the collection of transitive descriptor sets is available through the <code>[ProtoInfo].transitive_descriptor_sets</code> Starlark provider. See documentation in <code>ProtoInfo.java</code>.</p> <p>Recommended code organization:</p> <ul> <li> One <code>proto_library</code> rule per <code>.proto</code> file. <li> A file named <code>foo.proto</code> will be in a rule named <code>foo_proto</code>, which is located in the same package. <li> A <code>[language]_proto_library</code> that wraps a <code>proto_library</code> named <code>foo_proto</code> should be called <code>foo_[language]_proto</code>, and be located in the same package. </ul> <h3 id="proto_library_args">Arguments</h3> <table class="table table-condensed table-bordered table-params"> <colgroup> <col class="col-param" /> <col class="param-description" /> </colgroup> <thead> <tr> <th colspan="2">Attributes</th> </tr> </thead> <tbody> <tr> <td id="proto_library.name"><code>name</code></td> <td> <p><a href="/versions/7.2.0/concepts/labels#target-names">Name</a>; required</p> <p>A unique name for this target.</p> 
    </td>
  </tr>
            <tr>
    <td id="proto_library.deps">
      <code>deps</code>
    </td>
    <td>
                <p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; default is <code>[]</code></p>
                        The list of other <code>proto_library</code> rules that the target depends upon.
    A <code>proto_library</code> may only depend on other
    <code>proto_library</code> targets.
    It may not depend on language-specific libraries.

    </td>
  </tr>
                  <tr>
    <td id="proto_library.srcs">
      <code>srcs</code>
    </td>
    <td>
                <p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; default is <code>[]</code></p>
                        The list of <code>.proto</code> and <code>.protodevel</code> files that are
    processed to create the target. This is usually a non empty list. One usecase
    where <code>srcs</code> can be empty is an <i>alias-library</i>. This is a
    proto_library rule having one or more other proto_library in <code>deps</code>.
    This pattern can be used to e.g. export a public api under a persistent name.

    </td>
  </tr>
                            <tr>
    <td id="proto_library.allow_exports">
      <code>allow_exports</code>
    </td>
    <td>
                <p><a href="/versions/7.2.0/concepts/labels">Label</a>; default is <code>None</code></p>
                        An optional allowlist that prevents proto library to be reexported or used in
    lang_proto_library that is not in one of the listed packages.

    </td>
  </tr>
                                                                    <tr>
    <td id="proto_library.exports">
      <code>exports</code>
    </td>
    <td>
                <p>List of <a href="/versions/7.2.0/concepts/labels">labels</a>; default is <code>[]</code></p>
                        List of proto_library targets that can be referenced via "import public" in the proto
    source.

    </td>
  </tr>
                            <tr>
    <td id="proto_library.import_prefix">
      <code>import_prefix</code>
    </td>
    <td>
                <p>String; default is <code>""</code></p>
                        The prefix to add to the paths of the .proto files in this rule.

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

    <p>The prefix in the <code>strip_import_prefix</code> attribute is removed before this
    prefix is added.

    </td>
  </tr>
                                      <tr>
    <td id="proto_library.strip_import_prefix">
      <code>strip_import_prefix</code>
    </td>
    <td>
                <p>String; default is <code>""</code></p>
                        The prefix to strip from the paths of the .proto files in this rule.

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

    <p>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.

    <p>The prefix in the <code>import_prefix</code> attribute is added after this prefix is
    stripped.

    </td>
  </tr>
                                                  </tbody>
</table> <!-- Generated footer --> </body> </html>