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

<html devsite>
<head>
  <meta name="project_path" value="/_project.yaml">
  <meta name="book_path" value="/versions/6.4.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>



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

  <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>Deprecated. Please <a href="https://github.com/bazelbuild/rules_proto">
   https://github.com/bazelbuild/rules_proto</a> instead.
</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><code><a href="/versions/6.4.0/concepts/labels#target-names">Name</a>; required</code></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><code>List of <a href="/versions/6.4.0/concepts/labels">labels</a>; optional</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><code>String; required</code></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><code>String; optional; default is "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><code>String; optional; default is "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><code><a href="/versions/6.4.0/concepts/labels">Label</a>; optional</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=<executable>.</code>

        </td>
      </tr>
                      <tr>
        <td id="proto_lang_toolchain.plugin_format_flag">
          <code>plugin_format_flag</code>
        </td>
        <td>
                    <p><code>String; optional</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=<executable>.</code>

        </td>
      </tr>
                      <tr>
        <td id="proto_lang_toolchain.progress_message">
          <code>progress_message</code>
        </td>
        <td>
                    <p><code>String; optional; default is "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><code><a href="/versions/6.4.0/concepts/labels">Label</a>; optional</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><code><a href="/versions/6.4.0/concepts/labels">Label</a>; optional</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>

  <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="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><code><a href="/versions/6.4.0/concepts/labels#target-names">Name</a>; required</code></p>
          <p>A unique name for this target.</p>

        </td>
      </tr>
                <tr>
        <td id="proto_library.deps">
          <code>deps</code>
        </td>
        <td>
                    <p><code>List of <a href="/versions/6.4.0/concepts/labels">labels</a>; optional</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><code>List of <a href="/versions/6.4.0/concepts/labels">labels</a>; optional</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.exports">
          <code>exports</code>
        </td>
        <td>
                    <p><code>List of <a href="/versions/6.4.0/concepts/labels">labels</a>; optional</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><code>String; optional</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><code>String; optional</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>