Restructure docs

This commit is contained in:
Adam Liddell 2021-04-05 19:54:37 +00:00
parent a167438280
commit 92d4f039e7
34 changed files with 1258 additions and 1102 deletions

5
.gitignore vendored
View File

@ -1,5 +1,8 @@
__pycache__
/venv
bazel-*
node_modules
.idea
available_tests.txt
@ -8,3 +11,5 @@ csharp/nuget/nuget2config.json
ruby/.bundle
js/requirements/yarn-error.log
.vscode
/docs/build

View File

@ -3,10 +3,17 @@
rulegen:
bazel query '//example/routeguide/... - attr(tags, manual, //example/routeguide/...)' > available_tests.txt; \
bazel run --run_under="cd $$PWD && " //tools/rulegen -- --ref=$$(git describe --abbrev=0 --tags); \
rm available_tests.txt; \
rm available_tests.txt;
# Build docs locally
.PHONY: docs
docs:
python3 -m sphinx -c docs -a -E -T -W --keep-going docs/src docs/build
# Apply buildifier
.PHONY: buildifier
buildifier:
bazel run //tools:buildifier

View File

@ -11,6 +11,8 @@ Protobuf and gRPC rules for `Bazel <https://bazel.build>`_
and `gRPC <https://grpc.io>`_ code and libraries from
`proto_library <https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library>`_ targets
`Docs <https://rules_proto_grpc.aliddell.com>`__ | `GitHub <https://github.com/rules-proto-grpc/rules_proto_grpc>`__
.. image:: https://img.shields.io/github/v/tag/rules-proto-grpc/rules_proto_grpc?label=release&sort=semver&color=38a3a5
:alt: Latest Release
:target: https://github.com/rules-proto-grpc/rules_proto_grpc/releases
@ -56,24 +58,24 @@ Contents
- `Overview`_
- `Installation`_
- `Rules`_
- `Android </android>`_
- `Buf </buf>`_
- `C </c>`_
- `C++ </cpp>`_
- `C# </csharp>`_
- `D </d>`_
- `Documentation </doc>`_
- `Go </go>`_
- `grpc-gateway </grpc-gateway>`_
- `Java </java>`_
- `JavaScript </js>`_
- `Objective-C </objc>`_
- `PHP </php>`_
- `Python </python>`_
- `Ruby </ruby>`_
- `Rust </rust>`_
- `Scala </scala>`_
- `Swift </swift>`_
- `Android <android>`_
- `Buf <buf>`_
- `C <c>`_
- `C++ <cpp>`_
- `C# <csharp>`_
- `D <d>`_
- `Documentation <doc>`_
- `Go <go>`_
- `grpc-gateway <grpc-gateway>`_
- `Java <java>`_
- `JavaScript <js>`_
- `Objective-C <objc>`_
- `PHP <php>`_
- `Python <python>`_
- `Ruby <ruby>`_
- `Rust <rust>`_
- `Scala <scala>`_
- `Swift <swift>`_
- `Example Usage`_
- `Developers`_
- `Code Layout`_
@ -115,7 +117,7 @@ Installation
Add ``rules_proto_grpc`` to your ``WORKSPACE`` file and then look at the language specific examples linked below:
.. code-block:: starlark
.. code-block:: python
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
@ -152,428 +154,207 @@ Rules
* - Language
- Rule
- Description
* - `Android </android>`_
- `android_proto_compile </android#android_proto_compile>`_
- Generates an Android protobuf ``.jar`` file (`example </example/android/android_proto_compile>`_)
* - `Android </android>`_
- `android_grpc_compile </android#android_grpc_compile>`_
- Generates Android protobuf and gRPC ``.jar`` files (`example </example/android/android_grpc_compile>`_)
* - `Android </android>`_
- `android_proto_library </android#android_proto_library>`_
- Generates an Android protobuf library using ``android_library`` from ``rules_android`` (`example </example/android/android_proto_library>`_)
* - `Android </android>`_
- `android_grpc_library </android#android_grpc_library>`_
- Generates Android protobuf and gRPC library using ``android_library`` from ``rules_android`` (`example </example/android/android_grpc_library>`_)
* - `Buf </buf>`_
- `buf_proto_breaking_test </buf#buf_proto_breaking_test>`_
- Checks .proto files for breaking changes (`example </example/buf/buf_proto_breaking_test>`_)
* - `Buf </buf>`_
- `buf_proto_lint_test </buf#buf_proto_lint_test>`_
- Lints .proto files (`example </example/buf/buf_proto_lint_test>`_)
* - `C </c>`_
- `c_proto_compile </c#c_proto_compile>`_
- Generates C protobuf ``.h`` & ``.c`` files (`example </example/c/c_proto_compile>`_)
* - `C </c>`_
- `c_proto_library </c#c_proto_library>`_
- Generates a C protobuf library using ``cc_library``, with dependencies linked (`example </example/c/c_proto_library>`_)
* - `C++ </cpp>`_
- `cpp_proto_compile </cpp#cpp_proto_compile>`_
- Generates C++ protobuf ``.h`` & ``.cc`` files (`example </example/cpp/cpp_proto_compile>`_)
* - `C++ </cpp>`_
- `cpp_grpc_compile </cpp#cpp_grpc_compile>`_
- Generates C++ protobuf and gRPC ``.h`` & ``.cc`` files (`example </example/cpp/cpp_grpc_compile>`_)
* - `C++ </cpp>`_
- `cpp_proto_library </cpp#cpp_proto_library>`_
- Generates a C++ protobuf library using ``cc_library``, with dependencies linked (`example </example/cpp/cpp_proto_library>`_)
* - `C++ </cpp>`_
- `cpp_grpc_library </cpp#cpp_grpc_library>`_
- Generates a C++ protobuf and gRPC library using ``cc_library``, with dependencies linked (`example </example/cpp/cpp_grpc_library>`_)
* - `C# </csharp>`_
- `csharp_proto_compile </csharp#csharp_proto_compile>`_
- Generates C# protobuf ``.cs`` files (`example </example/csharp/csharp_proto_compile>`_)
* - `C# </csharp>`_
- `csharp_grpc_compile </csharp#csharp_grpc_compile>`_
- Generates C# protobuf and gRPC ``.cs`` files (`example </example/csharp/csharp_grpc_compile>`_)
* - `C# </csharp>`_
- `csharp_proto_library </csharp#csharp_proto_library>`_
- Generates a C# protobuf library using ``csharp_library`` from ``rules_dotnet``. Note that the library name must end in ``.dll`` (`example </example/csharp/csharp_proto_library>`_)
* - `C# </csharp>`_
- `csharp_grpc_library </csharp#csharp_grpc_library>`_
- Generates a C# protobuf and gRPC library using ``csharp_library`` from ``rules_dotnet``. Note that the library name must end in ``.dll`` (`example </example/csharp/csharp_grpc_library>`_)
* - `D </d>`_
- `d_proto_compile </d#d_proto_compile>`_
- Generates D protobuf ``.d`` files (`example </example/d/d_proto_compile>`_)
* - `D </d>`_
- `d_proto_library </d#d_proto_library>`_
- Generates a D protobuf library using ``d_library`` from ``rules_d`` (`example </example/d/d_proto_library>`_)
* - `Documentation </doc>`_
- `doc_docbook_compile </doc#doc_docbook_compile>`_
- Generates DocBook ``.xml`` documentation file (`example </example/doc/doc_docbook_compile>`_)
* - `Documentation </doc>`_
- `doc_html_compile </doc#doc_html_compile>`_
- Generates ``.html`` documentation file (`example </example/doc/doc_html_compile>`_)
* - `Documentation </doc>`_
- `doc_json_compile </doc#doc_json_compile>`_
- Generates ``.json`` documentation file (`example </example/doc/doc_json_compile>`_)
* - `Documentation </doc>`_
- `doc_markdown_compile </doc#doc_markdown_compile>`_
- Generates Markdown ``.md`` documentation file (`example </example/doc/doc_markdown_compile>`_)
* - `Go </go>`_
- `go_proto_compile </go#go_proto_compile>`_
- Generates Go protobuf ``.go`` files (`example </example/go/go_proto_compile>`_)
* - `Go </go>`_
- `go_grpc_compile </go#go_grpc_compile>`_
- Generates Go protobuf and gRPC ``.go`` files (`example </example/go/go_grpc_compile>`_)
* - `Go </go>`_
- `go_proto_library </go#go_proto_library>`_
- Generates a Go protobuf library using ``go_library`` from ``rules_go`` (`example </example/go/go_proto_library>`_)
* - `Go </go>`_
- `go_grpc_library </go#go_grpc_library>`_
- Generates a Go protobuf and gRPC library using ``go_library`` from ``rules_go`` (`example </example/go/go_grpc_library>`_)
* - `grpc-gateway </grpc-gateway>`_
- `gateway_grpc_compile </grpc-gateway#gateway_grpc_compile>`_
- Generates grpc-gateway ``.go`` files (`example </example/grpc-gateway/gateway_grpc_compile>`_)
* - `grpc-gateway </grpc-gateway>`_
- `gateway_openapiv2_compile </grpc-gateway#gateway_openapiv2_compile>`_
- Generates grpc-gateway OpenAPI v2 ``.json`` files (`example </example/grpc-gateway/gateway_openapiv2_compile>`_)
* - `grpc-gateway </grpc-gateway>`_
- `gateway_grpc_library </grpc-gateway#gateway_grpc_library>`_
- Generates grpc-gateway library files (`example </example/grpc-gateway/gateway_grpc_library>`_)
* - `Java </java>`_
- `java_proto_compile </java#java_proto_compile>`_
- Generates a Java protobuf srcjar file (`example </example/java/java_proto_compile>`_)
* - `Java </java>`_
- `java_grpc_compile </java#java_grpc_compile>`_
- Generates a Java protobuf and gRPC srcjar file (`example </example/java/java_grpc_compile>`_)
* - `Java </java>`_
- `java_proto_library </java#java_proto_library>`_
- Generates a Java protobuf library using ``java_library`` (`example </example/java/java_proto_library>`_)
* - `Java </java>`_
- `java_grpc_library </java#java_grpc_library>`_
- Generates a Java protobuf and gRPC library using ``java_library`` (`example </example/java/java_grpc_library>`_)
* - `JavaScript </js>`_
- `js_proto_compile </js#js_proto_compile>`_
- Generates JavaScript protobuf ``.js`` and ``.d.ts`` files (`example </example/js/js_proto_compile>`_)
* - `JavaScript </js>`_
- `js_grpc_node_compile </js#js_grpc_node_compile>`_
- Generates JavaScript protobuf and gRPC-node ``.js`` and ``.d.ts`` files (`example </example/js/js_grpc_node_compile>`_)
* - `JavaScript </js>`_
- `js_grpc_web_compile </js#js_grpc_web_compile>`_
- Generates JavaScript protobuf and gRPC-Web ``.js`` and ``.d.ts`` files (`example </example/js/js_grpc_web_compile>`_)
* - `JavaScript </js>`_
- `js_proto_library </js#js_proto_library>`_
- Generates a JavaScript protobuf library using ``js_library`` from ``rules_nodejs`` (`example </example/js/js_proto_library>`_)
* - `JavaScript </js>`_
- `js_grpc_node_library </js#js_grpc_node_library>`_
- Generates a Node.js protobuf + gRPC-node library using ``js_library`` from ``rules_nodejs`` (`example </example/js/js_grpc_node_library>`_)
* - `JavaScript </js>`_
- `js_grpc_web_library </js#js_grpc_web_library>`_
- Generates a JavaScript protobuf + gRPC-Web library using ``js_library`` from ``rules_nodejs`` (`example </example/js/js_grpc_web_library>`_)
* - `Objective-C </objc>`_
- `objc_proto_compile </objc#objc_proto_compile>`_
- Generates Objective-C protobuf ``.m`` & ``.h`` files (`example </example/objc/objc_proto_compile>`_)
* - `Objective-C </objc>`_
- `objc_grpc_compile </objc#objc_grpc_compile>`_
- Generates Objective-C protobuf and gRPC ``.m`` & ``.h`` files (`example </example/objc/objc_grpc_compile>`_)
* - `Objective-C </objc>`_
- `objc_proto_library </objc#objc_proto_library>`_
- Generates an Objective-C protobuf library using ``objc_library`` (`example </example/objc/objc_proto_library>`_)
* - `Objective-C </objc>`_
- `objc_grpc_library </objc#objc_grpc_library>`_
- Generates an Objective-C protobuf and gRPC library using ``objc_library`` (`example </example/objc/objc_grpc_library>`_)
* - `PHP </php>`_
- `php_proto_compile </php#php_proto_compile>`_
- Generates PHP protobuf ``.php`` files (`example </example/php/php_proto_compile>`_)
* - `PHP </php>`_
- `php_grpc_compile </php#php_grpc_compile>`_
- Generates PHP protobuf and gRPC ``.php`` files (`example </example/php/php_grpc_compile>`_)
* - `Python </python>`_
- `python_proto_compile </python#python_proto_compile>`_
- Generates Python protobuf ``.py`` files (`example </example/python/python_proto_compile>`_)
* - `Python </python>`_
- `python_grpc_compile </python#python_grpc_compile>`_
- Generates Python protobuf and gRPC ``.py`` files (`example </example/python/python_grpc_compile>`_)
* - `Python </python>`_
- `python_grpclib_compile </python#python_grpclib_compile>`_
- Generates Python protobuf and grpclib ``.py`` files (supports Python 3 only) (`example </example/python/python_grpclib_compile>`_)
* - `Python </python>`_
- `python_proto_library </python#python_proto_library>`_
- Generates a Python protobuf library using ``py_library`` from ``rules_python`` (`example </example/python/python_proto_library>`_)
* - `Python </python>`_
- `python_grpc_library </python#python_grpc_library>`_
- Generates a Python protobuf and gRPC library using ``py_library`` from ``rules_python`` (`example </example/python/python_grpc_library>`_)
* - `Python </python>`_
- `python_grpclib_library </python#python_grpclib_library>`_
- Generates a Python protobuf and grpclib library using ``py_library`` from ``rules_python`` (supports Python 3 only) (`example </example/python/python_grpclib_library>`_)
* - `Ruby </ruby>`_
- `ruby_proto_compile </ruby#ruby_proto_compile>`_
- Generates Ruby protobuf ``.rb`` files (`example </example/ruby/ruby_proto_compile>`_)
* - `Ruby </ruby>`_
- `ruby_grpc_compile </ruby#ruby_grpc_compile>`_
- Generates Ruby protobuf and gRPC ``.rb`` files (`example </example/ruby/ruby_grpc_compile>`_)
* - `Ruby </ruby>`_
- `ruby_proto_library </ruby#ruby_proto_library>`_
- Generates a Ruby protobuf library using ``ruby_library`` from ``rules_ruby`` (`example </example/ruby/ruby_proto_library>`_)
* - `Ruby </ruby>`_
- `ruby_grpc_library </ruby#ruby_grpc_library>`_
- Generates a Ruby protobuf and gRPC library using ``ruby_library`` from ``rules_ruby`` (`example </example/ruby/ruby_grpc_library>`_)
* - `Rust </rust>`_
- `rust_proto_compile </rust#rust_proto_compile>`_
- Generates Rust protobuf ``.rs`` files (`example </example/rust/rust_proto_compile>`_)
* - `Rust </rust>`_
- `rust_grpc_compile </rust#rust_grpc_compile>`_
- Generates Rust protobuf and gRPC ``.rs`` files (`example </example/rust/rust_grpc_compile>`_)
* - `Rust </rust>`_
- `rust_proto_library </rust#rust_proto_library>`_
- Generates a Rust protobuf library using ``rust_library`` from ``rules_rust`` (`example </example/rust/rust_proto_library>`_)
* - `Rust </rust>`_
- `rust_grpc_library </rust#rust_grpc_library>`_
- Generates a Rust protobuf and gRPC library using ``rust_library`` from ``rules_rust`` (`example </example/rust/rust_grpc_library>`_)
* - `Scala </scala>`_
- `scala_proto_compile </scala#scala_proto_compile>`_
- Generates a Scala protobuf ``.jar`` file (`example </example/scala/scala_proto_compile>`_)
* - `Scala </scala>`_
- `scala_grpc_compile </scala#scala_grpc_compile>`_
- Generates Scala protobuf and gRPC ``.jar`` file (`example </example/scala/scala_grpc_compile>`_)
* - `Scala </scala>`_
- `scala_proto_library </scala#scala_proto_library>`_
- Generates a Scala protobuf library using ``scala_library`` from ``rules_scala`` (`example </example/scala/scala_proto_library>`_)
* - `Scala </scala>`_
- `scala_grpc_library </scala#scala_grpc_library>`_
- Generates a Scala protobuf and gRPC library using ``scala_library`` from ``rules_scala`` (`example </example/scala/scala_grpc_library>`_)
* - `Swift </swift>`_
- `swift_proto_compile </swift#swift_proto_compile>`_
- Generates Swift protobuf ``.swift`` files (`example </example/swift/swift_proto_compile>`_)
* - `Swift </swift>`_
- `swift_grpc_compile </swift#swift_grpc_compile>`_
- Generates Swift protobuf and gRPC ``.swift`` files (`example </example/swift/swift_grpc_compile>`_)
* - `Swift </swift>`_
- `swift_proto_library </swift#swift_proto_library>`_
- Generates a Swift protobuf library using ``swift_library`` from ``rules_swift`` (`example </example/swift/swift_proto_library>`_)
* - `Swift </swift>`_
- `swift_grpc_library </swift#swift_grpc_library>`_
- Generates a Swift protobuf and gRPC library using ``swift_library`` from ``rules_swift`` (`example </example/swift/swift_grpc_library>`_)
Example Usage
-------------
These steps walk through the actions required to go from a raw ``.proto`` file to a C++ library. Other languages will have
a similar high-level layout.
**Step 1**: Write a Protocol Buffer .proto file (example: ``thing.proto``):
.. code-block:: proto
syntax = "proto3";
package example;
import "google/protobuf/any.proto";
message Thing {
string name = 1;
google.protobuf.Any payload = 2;
}
**Step 2**: Write a ``BAZEL.build`` file with a
`proto_library <https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library>`_ target:
.. code-block:: starlark
proto_library(
name = "thing_proto",
srcs = ["thing.proto"],
deps = ["@com_google_protobuf//:any_proto"],
)
In this example we have a dependency on a well-known type ``any.proto``, hence the ``proto_library`` to ``proto_library``
dependency (``"@com_google_protobuf//:any_proto"``)
**Step 3**: Add a ``cpp_proto_compile`` target
**Note**: In this example ``thing.proto`` does not include service definitions (gRPC). For protos with services, use the
``cpp_grpc_compile`` rule instead.
.. code-block:: starlark
# BUILD.bazel
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_compile")
cpp_proto_compile(
name = "cpp_thing_proto",
protos = [":thing_proto"],
)
But wait, before we can build this, we need to load the dependencies necessary for this rule
(see `cpp </cpp>`_):
**Step 4**: Load the workspace macro corresponding to the build rule.
.. code-block:: starlark
# WORKSPACE
load("@rules_proto_grpc//cpp:repositories.bzl", "cpp_repos")
cpp_repos()
We're now ready to build the target.
**Step 5**: Build it!
.. code-block:: bash
$ bazel build //example/proto:cpp_thing_proto
Target //example/proto:cpp_thing_proto up-to-date:
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc
If we were only interested in the generated files, the ``cpp_grpc_compile`` rule would be fine. However, for
convenience we'd rather have the outputs compiled into a C++ library. To do that, let's change the rule from
``cpp_proto_compile`` to ``cpp_proto_library``:
.. code-block:: starlark
# BUILD.bazel
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_library")
cpp_proto_library(
name = "cpp_thing_proto",
protos = [":thing_proto"],
)
.. code-block:: bash
$ bazel build //example/proto:cpp_thing_proto
Target //example/proto:cpp_thing_proto up-to-date:
bazel-bin/example/proto/libcpp_thing_proto.a
bazel-bin/example/proto/libcpp_thing_proto.so bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc
This way, we can use ``//example/proto:cpp_thing_proto`` as a dependency of any other ``cc_library`` or ``cc_binary`` target
as per normal.
**Note**: The ``cpp_proto_library`` target implicitly calls ``cpp_proto_compile``, and we can access that rule's by adding
``_pb`` at the end of the target name, like ``bazel build //example/proto:cpp_thing_proto_pb``
Developers
----------
Code Layout
***********
Each language ``{lang}`` has a top-level subdirectory that contains:
1. ``{lang}/README.rst``: Generated documentation for the language rules
1. ``{lang}/repositories.bzl``: Macro functions that declare repository rule dependencies for that language
2. ``{lang}/{rule}.bzl``: Rule implementations of the form ``{lang}_{kind}_{type}``, where ``kind`` is one of ``proto|grpc`` and
``type`` is one of ``compile|library``
3. ``{lang}/BUILD.bazel``: ``proto_plugin()`` declarations for the available plugins for the language
4. ``example/{lang}/{rule}/``: Generated ``WORKSPACE`` and ``BUILD.bazel`` demonstrating standalone usage of the rules
5. ``{lang}/example/routeguide/``: Example routeguide example implementation, if possible
Rule Generation
***************
To help maintain consistency of the rule implementations and documentation, all of the rule implementations are
generated by the tool ``//tools/rulegen``. Changes in the main ``README.rst`` should be placed in
``tools/rulegen/README.header.rst`` or ``tools/rulegen/README.footer.rst```. Changes to generated rules should be put in the
source files (example: ``tools/rulegen/java.go``).
Developing Custom Plugins
*************************
Generally, follow the pattern seen in the multiple language examples in this
repository. The basic idea is:
1. Load the plugin rule: ``load("@rules_proto_grpc//:defs.bzl", "proto_plugin")``
2. Define the rule, giving it a ``name``, ``options`` (not mandatory), ``tool`` and ``outputs``. ``tool`` is a label that refers
to the binary executable for the plugin itself
3. Choose your output type (pick one!):
- ``outputs``: A list of strings patterns that predicts the pattern of files generated by the plugin. For plugins that
produce one output file per input proto file
- ``out``: The name of a single output file generated by the plugin
- ``output_directory``: Set to true if your plugin generates files in a non-predictable way. e.g. if the output paths
depend on the service names within the files
4. Create a compilation rule and aspect using the following template:
.. code-block:: starlark
load("@rules_proto//proto:defs.bzl", "ProtoInfo")
load(
"@rules_proto_grpc//:defs.bzl",
"ProtoLibraryAspectNodeInfo",
"ProtoPluginInfo",
"proto_compile_aspect_attrs",
"proto_compile_aspect_impl",
"proto_compile_attrs",
"proto_compile_impl",
)
# Create aspect
example_aspect = aspect(
implementation = proto_compile_aspect_impl,
provides = [ProtoLibraryAspectNodeInfo],
attr_aspects = ["deps"],
attrs = dict(
proto_compile_aspect_attrs,
_plugins = attr.label_list(
doc = "List of protoc plugins to apply",
providers = [ProtoPluginInfo],
default = [
Label("//<LABEL OF YOUR PLUGIN>"),
],
),
_prefix = attr.string(
doc = "String used to disambiguate aspects when generating outputs",
default = "example_aspect",
),
),
toolchains = ["@rules_proto_grpc//protobuf:toolchain_type"],
)
# Create compile rule to apply aspect
_rule = rule(
implementation = proto_compile_impl,
attrs = dict(
proto_compile_attrs,
protos = attr.label_list(
mandatory = False, # TODO: set to true in 4.0.0 when deps removed below
providers = [ProtoInfo],
doc = "List of labels that provide the ProtoInfo provider (such as proto_library from rules_proto)",
),
deps = attr.label_list(
mandatory = False,
providers = [ProtoInfo, ProtoLibraryAspectNodeInfo],
aspects = [example_aspect],
doc = "DEPRECATED: Use protos attr",
),
_plugins = attr.label_list(
providers = [ProtoPluginInfo],
default = [
Label("//<LABEL OF YOUR PLUGIN>"),
],
doc = "List of protoc plugins to apply",
),
),
toolchains = [str(Label("//protobuf:toolchain_type"))],
)
# Create macro for converting attrs and passing to compile
def example_compile(**kwargs):
_rule(
verbose_string = "{}".format(kwargs.get("verbose", 0)),
**kwargs
)
* - `Android <android>`_
- `android_proto_compile <android#android_proto_compile>`_
- Generates an Android protobuf ``.jar`` file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/android/android_proto_compile>`__)
* - `Android <android>`_
- `android_grpc_compile <android#android_grpc_compile>`_
- Generates Android protobuf and gRPC ``.jar`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/android/android_grpc_compile>`__)
* - `Android <android>`_
- `android_proto_library <android#android_proto_library>`_
- Generates an Android protobuf library using ``android_library`` from ``rules_android`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/android/android_proto_library>`__)
* - `Android <android>`_
- `android_grpc_library <android#android_grpc_library>`_
- Generates Android protobuf and gRPC library using ``android_library`` from ``rules_android`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/android/android_grpc_library>`__)
* - `Buf <buf>`_
- `buf_proto_breaking_test <buf#buf_proto_breaking_test>`_
- Checks .proto files for breaking changes (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/buf/buf_proto_breaking_test>`__)
* - `Buf <buf>`_
- `buf_proto_lint_test <buf#buf_proto_lint_test>`_
- Lints .proto files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/buf/buf_proto_lint_test>`__)
* - `C <c>`_
- `c_proto_compile <c#c_proto_compile>`_
- Generates C protobuf ``.h`` & ``.c`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/c/c_proto_compile>`__)
* - `C <c>`_
- `c_proto_library <c#c_proto_library>`_
- Generates a C protobuf library using ``cc_library``, with dependencies linked (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/c/c_proto_library>`__)
* - `C++ <cpp>`_
- `cpp_proto_compile <cpp#cpp_proto_compile>`_
- Generates C++ protobuf ``.h`` & ``.cc`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/cpp/cpp_proto_compile>`__)
* - `C++ <cpp>`_
- `cpp_grpc_compile <cpp#cpp_grpc_compile>`_
- Generates C++ protobuf and gRPC ``.h`` & ``.cc`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/cpp/cpp_grpc_compile>`__)
* - `C++ <cpp>`_
- `cpp_proto_library <cpp#cpp_proto_library>`_
- Generates a C++ protobuf library using ``cc_library``, with dependencies linked (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/cpp/cpp_proto_library>`__)
* - `C++ <cpp>`_
- `cpp_grpc_library <cpp#cpp_grpc_library>`_
- Generates a C++ protobuf and gRPC library using ``cc_library``, with dependencies linked (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/cpp/cpp_grpc_library>`__)
* - `C# <csharp>`_
- `csharp_proto_compile <csharp#csharp_proto_compile>`_
- Generates C# protobuf ``.cs`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/csharp/csharp_proto_compile>`__)
* - `C# <csharp>`_
- `csharp_grpc_compile <csharp#csharp_grpc_compile>`_
- Generates C# protobuf and gRPC ``.cs`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/csharp/csharp_grpc_compile>`__)
* - `C# <csharp>`_
- `csharp_proto_library <csharp#csharp_proto_library>`_
- Generates a C# protobuf library using ``csharp_library`` from ``rules_dotnet``. Note that the library name must end in ``.dll`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/csharp/csharp_proto_library>`__)
* - `C# <csharp>`_
- `csharp_grpc_library <csharp#csharp_grpc_library>`_
- Generates a C# protobuf and gRPC library using ``csharp_library`` from ``rules_dotnet``. Note that the library name must end in ``.dll`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/csharp/csharp_grpc_library>`__)
* - `D <d>`_
- `d_proto_compile <d#d_proto_compile>`_
- Generates D protobuf ``.d`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/d/d_proto_compile>`__)
* - `D <d>`_
- `d_proto_library <d#d_proto_library>`_
- Generates a D protobuf library using ``d_library`` from ``rules_d`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/d/d_proto_library>`__)
* - `Documentation <doc>`_
- `doc_docbook_compile <doc#doc_docbook_compile>`_
- Generates DocBook ``.xml`` documentation file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/doc/doc_docbook_compile>`__)
* - `Documentation <doc>`_
- `doc_html_compile <doc#doc_html_compile>`_
- Generates ``.html`` documentation file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/doc/doc_html_compile>`__)
* - `Documentation <doc>`_
- `doc_json_compile <doc#doc_json_compile>`_
- Generates ``.json`` documentation file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/doc/doc_json_compile>`__)
* - `Documentation <doc>`_
- `doc_markdown_compile <doc#doc_markdown_compile>`_
- Generates Markdown ``.md`` documentation file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/doc/doc_markdown_compile>`__)
* - `Go <go>`_
- `go_proto_compile <go#go_proto_compile>`_
- Generates Go protobuf ``.go`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/go/go_proto_compile>`__)
* - `Go <go>`_
- `go_grpc_compile <go#go_grpc_compile>`_
- Generates Go protobuf and gRPC ``.go`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/go/go_grpc_compile>`__)
* - `Go <go>`_
- `go_proto_library <go#go_proto_library>`_
- Generates a Go protobuf library using ``go_library`` from ``rules_go`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/go/go_proto_library>`__)
* - `Go <go>`_
- `go_grpc_library <go#go_grpc_library>`_
- Generates a Go protobuf and gRPC library using ``go_library`` from ``rules_go`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/go/go_grpc_library>`__)
* - `grpc-gateway <grpc-gateway>`_
- `gateway_grpc_compile <grpc-gateway#gateway_grpc_compile>`_
- Generates grpc-gateway ``.go`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/grpc-gateway/gateway_grpc_compile>`__)
* - `grpc-gateway <grpc-gateway>`_
- `gateway_openapiv2_compile <grpc-gateway#gateway_openapiv2_compile>`_
- Generates grpc-gateway OpenAPI v2 ``.json`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/grpc-gateway/gateway_openapiv2_compile>`__)
* - `grpc-gateway <grpc-gateway>`_
- `gateway_grpc_library <grpc-gateway#gateway_grpc_library>`_
- Generates grpc-gateway library files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/grpc-gateway/gateway_grpc_library>`__)
* - `Java <java>`_
- `java_proto_compile <java#java_proto_compile>`_
- Generates a Java protobuf srcjar file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/java/java_proto_compile>`__)
* - `Java <java>`_
- `java_grpc_compile <java#java_grpc_compile>`_
- Generates a Java protobuf and gRPC srcjar file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/java/java_grpc_compile>`__)
* - `Java <java>`_
- `java_proto_library <java#java_proto_library>`_
- Generates a Java protobuf library using ``java_library`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/java/java_proto_library>`__)
* - `Java <java>`_
- `java_grpc_library <java#java_grpc_library>`_
- Generates a Java protobuf and gRPC library using ``java_library`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/java/java_grpc_library>`__)
* - `JavaScript <js>`_
- `js_proto_compile <js#js_proto_compile>`_
- Generates JavaScript protobuf ``.js`` and ``.d.ts`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/js/js_proto_compile>`__)
* - `JavaScript <js>`_
- `js_grpc_node_compile <js#js_grpc_node_compile>`_
- Generates JavaScript protobuf and gRPC-node ``.js`` and ``.d.ts`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/js/js_grpc_node_compile>`__)
* - `JavaScript <js>`_
- `js_grpc_web_compile <js#js_grpc_web_compile>`_
- Generates JavaScript protobuf and gRPC-Web ``.js`` and ``.d.ts`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/js/js_grpc_web_compile>`__)
* - `JavaScript <js>`_
- `js_proto_library <js#js_proto_library>`_
- Generates a JavaScript protobuf library using ``js_library`` from ``rules_nodejs`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/js/js_proto_library>`__)
* - `JavaScript <js>`_
- `js_grpc_node_library <js#js_grpc_node_library>`_
- Generates a Node.js protobuf + gRPC-node library using ``js_library`` from ``rules_nodejs`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/js/js_grpc_node_library>`__)
* - `JavaScript <js>`_
- `js_grpc_web_library <js#js_grpc_web_library>`_
- Generates a JavaScript protobuf + gRPC-Web library using ``js_library`` from ``rules_nodejs`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/js/js_grpc_web_library>`__)
* - `Objective-C <objc>`_
- `objc_proto_compile <objc#objc_proto_compile>`_
- Generates Objective-C protobuf ``.m`` & ``.h`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/objc/objc_proto_compile>`__)
* - `Objective-C <objc>`_
- `objc_grpc_compile <objc#objc_grpc_compile>`_
- Generates Objective-C protobuf and gRPC ``.m`` & ``.h`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/objc/objc_grpc_compile>`__)
* - `Objective-C <objc>`_
- `objc_proto_library <objc#objc_proto_library>`_
- Generates an Objective-C protobuf library using ``objc_library`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/objc/objc_proto_library>`__)
* - `Objective-C <objc>`_
- `objc_grpc_library <objc#objc_grpc_library>`_
- Generates an Objective-C protobuf and gRPC library using ``objc_library`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/objc/objc_grpc_library>`__)
* - `PHP <php>`_
- `php_proto_compile <php#php_proto_compile>`_
- Generates PHP protobuf ``.php`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/php/php_proto_compile>`__)
* - `PHP <php>`_
- `php_grpc_compile <php#php_grpc_compile>`_
- Generates PHP protobuf and gRPC ``.php`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/php/php_grpc_compile>`__)
* - `Python <python>`_
- `python_proto_compile <python#python_proto_compile>`_
- Generates Python protobuf ``.py`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/python/python_proto_compile>`__)
* - `Python <python>`_
- `python_grpc_compile <python#python_grpc_compile>`_
- Generates Python protobuf and gRPC ``.py`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/python/python_grpc_compile>`__)
* - `Python <python>`_
- `python_grpclib_compile <python#python_grpclib_compile>`_
- Generates Python protobuf and grpclib ``.py`` files (supports Python 3 only) (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/python/python_grpclib_compile>`__)
* - `Python <python>`_
- `python_proto_library <python#python_proto_library>`_
- Generates a Python protobuf library using ``py_library`` from ``rules_python`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/python/python_proto_library>`__)
* - `Python <python>`_
- `python_grpc_library <python#python_grpc_library>`_
- Generates a Python protobuf and gRPC library using ``py_library`` from ``rules_python`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/python/python_grpc_library>`__)
* - `Python <python>`_
- `python_grpclib_library <python#python_grpclib_library>`_
- Generates a Python protobuf and grpclib library using ``py_library`` from ``rules_python`` (supports Python 3 only) (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/python/python_grpclib_library>`__)
* - `Ruby <ruby>`_
- `ruby_proto_compile <ruby#ruby_proto_compile>`_
- Generates Ruby protobuf ``.rb`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/ruby/ruby_proto_compile>`__)
* - `Ruby <ruby>`_
- `ruby_grpc_compile <ruby#ruby_grpc_compile>`_
- Generates Ruby protobuf and gRPC ``.rb`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/ruby/ruby_grpc_compile>`__)
* - `Ruby <ruby>`_
- `ruby_proto_library <ruby#ruby_proto_library>`_
- Generates a Ruby protobuf library using ``ruby_library`` from ``rules_ruby`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/ruby/ruby_proto_library>`__)
* - `Ruby <ruby>`_
- `ruby_grpc_library <ruby#ruby_grpc_library>`_
- Generates a Ruby protobuf and gRPC library using ``ruby_library`` from ``rules_ruby`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/ruby/ruby_grpc_library>`__)
* - `Rust <rust>`_
- `rust_proto_compile <rust#rust_proto_compile>`_
- Generates Rust protobuf ``.rs`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/rust/rust_proto_compile>`__)
* - `Rust <rust>`_
- `rust_grpc_compile <rust#rust_grpc_compile>`_
- Generates Rust protobuf and gRPC ``.rs`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/rust/rust_grpc_compile>`__)
* - `Rust <rust>`_
- `rust_proto_library <rust#rust_proto_library>`_
- Generates a Rust protobuf library using ``rust_library`` from ``rules_rust`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/rust/rust_proto_library>`__)
* - `Rust <rust>`_
- `rust_grpc_library <rust#rust_grpc_library>`_
- Generates a Rust protobuf and gRPC library using ``rust_library`` from ``rules_rust`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/rust/rust_grpc_library>`__)
* - `Scala <scala>`_
- `scala_proto_compile <scala#scala_proto_compile>`_
- Generates a Scala protobuf ``.jar`` file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/scala/scala_proto_compile>`__)
* - `Scala <scala>`_
- `scala_grpc_compile <scala#scala_grpc_compile>`_
- Generates Scala protobuf and gRPC ``.jar`` file (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/scala/scala_grpc_compile>`__)
* - `Scala <scala>`_
- `scala_proto_library <scala#scala_proto_library>`_
- Generates a Scala protobuf library using ``scala_library`` from ``rules_scala`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/scala/scala_proto_library>`__)
* - `Scala <scala>`_
- `scala_grpc_library <scala#scala_grpc_library>`_
- Generates a Scala protobuf and gRPC library using ``scala_library`` from ``rules_scala`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/scala/scala_grpc_library>`__)
* - `Swift <swift>`_
- `swift_proto_compile <swift#swift_proto_compile>`_
- Generates Swift protobuf ``.swift`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/swift/swift_proto_compile>`__)
* - `Swift <swift>`_
- `swift_grpc_compile <swift#swift_grpc_compile>`_
- Generates Swift protobuf and gRPC ``.swift`` files (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/swift/swift_grpc_compile>`__)
* - `Swift <swift>`_
- `swift_proto_library <swift#swift_proto_library>`_
- Generates a Swift protobuf library using ``swift_library`` from ``rules_swift`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/swift/swift_proto_library>`__)
* - `Swift <swift>`_
- `swift_grpc_library <swift#swift_grpc_library>`_
- Generates a Swift protobuf and gRPC library using ``swift_library`` from ``rules_swift`` (`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/swift/swift_grpc_library>`__)
License
-------

90
docs/conf.py Normal file
View File

@ -0,0 +1,90 @@
import datetime
# -- Project information -----------------------------------------------------
project = 'rules_proto_grpc'
copyright = '{}, rules_proto_grpc authors - Apache 2.0 License'.format(
datetime.date.today().year
)
author = 'rules_proto_grpc authors'
release = ''
version = release
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
# Internal
'sphinx.ext.githubpages',
# External
'sphinx_sitemap',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['.ipynb_checkpoints', '**/.ipynb_checkpoints']
# Code highlighting
pygments_style = 'monokai'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'
# Logo and favicon
html_logo = 'src/_static/logo.svg'
html_favicon = 'src/_static/logo-400.png'
# Base URL for docs
# Used to generate CNAME file
html_baseurl = 'https://rules_proto_grpc.aliddell.com'
# Extra vars to provide to templating
html_context = {
'baseurl': html_baseurl,
'icon_png': 'logo.png'
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['src/_static']
# Theme options
html_theme_options = {
'sidebar_hide_name': True,
'light_css_variables': {
'color-brand-primary': '#38a3a5',
'color-brand-content': '#38a3a5',
},
'dark_css_variables': {
'color-brand-primary': '#38a3a5',
'color-brand-content': '#38a3a5',
},
}
# Disable footer
html_show_sphinx = False
# Add CSS files
html_css_files = []
# Extra files to include
html_extra_path = [
'src/robots.txt',
]
# Sitemap options
sitemap_url_scheme = '{lang}{link}'

3
docs/requirements.txt Normal file
View File

@ -0,0 +1,3 @@
furo==2021.3.20b30
Sphinx==3.5.3
sphinx-sitemap==2.2.0

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

View File

Before

Width:  |  Height:  |  Size: 7.0 KiB

After

Width:  |  Height:  |  Size: 7.0 KiB

View File

@ -1,10 +1,15 @@
Android rules
=============
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Android
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Android
Android
=======
Rules for generating Android protobuf and gRPC ``.jar`` files and libraries using standard Protocol Buffers and `gRPC-Java <https://github.com/grpc/grpc-java>`_. Libraries are created with ``android_library`` from `rules_android <https://github.com/bazelbuild/rules_android>`_
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating Android protobuf and gRPC ``.jar`` files and libraries usin
* - `android_grpc_library <#android_grpc_library>`_
- Generates Android protobuf and gRPC library using ``android_library`` from ``rules_android``
``android_proto_compile``
-------------------------
android_proto_compile
---------------------
Generates an Android protobuf ``.jar`` file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//android:repositories.bzl", rules_proto_grpc_android_repos = "android_repos")
@ -35,7 +40,7 @@ Generates an Android protobuf ``.jar`` file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//android:defs.bzl", "android_proto_compile")
@ -58,6 +63,7 @@ Attributes
**********
.. list-table:: Attributes for android_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -68,7 +74,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -96,15 +102,15 @@ Plugins
- ``@rules_proto_grpc//android:javalite_plugin``
``android_grpc_compile``
------------------------
android_grpc_compile
--------------------
Generates Android protobuf and gRPC ``.jar`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//android:repositories.bzl", rules_proto_grpc_android_repos = "android_repos")
@ -131,7 +137,7 @@ Generates Android protobuf and gRPC ``.jar`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//android:defs.bzl", "android_grpc_compile")
@ -149,6 +155,7 @@ Attributes
**********
.. list-table:: Attributes for android_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -159,7 +166,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -188,15 +195,15 @@ Plugins
- ``@rules_proto_grpc//android:javalite_plugin``
- ``@rules_proto_grpc//android:grpc_javalite_plugin``
``android_proto_library``
-------------------------
android_proto_library
---------------------
Generates an Android protobuf library using ``android_library`` from ``rules_android``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
# The set of dependencies loaded here is excessive for android proto alone
# (but simplifies our setup)
@ -229,7 +236,7 @@ Generates an Android protobuf library using ``android_library`` from ``rules_and
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//android:defs.bzl", "android_proto_library")
@ -254,6 +261,7 @@ Attributes
**********
.. list-table:: Attributes for android_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -264,7 +272,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -297,15 +305,15 @@ Attributes
- ``[]``
- List of labels to pass as exports attr to underlying lang_library rule
``android_grpc_library``
------------------------
android_grpc_library
--------------------
Generates Android protobuf and gRPC library using ``android_library`` from ``rules_android``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//android:repositories.bzl", rules_proto_grpc_android_repos = "android_repos")
@ -336,7 +344,7 @@ Generates Android protobuf and gRPC library using ``android_library`` from ``rul
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//android:defs.bzl", "android_grpc_library")
@ -355,6 +363,7 @@ Attributes
**********
.. list-table:: Attributes for android_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -365,7 +374,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,5 +1,10 @@
Buf rules
=========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Buf
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Buf
Buf
===
Rules for linting and detecting breaking changes in .proto files with `Buf <https://buf.build>`_.
@ -8,7 +13,7 @@ Note that these rules behave differently from the other rules in this repo, sinc
Only Linux and Darwin (MacOS) is currently supported by Buf.
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,8 +23,8 @@ Only Linux and Darwin (MacOS) is currently supported by Buf.
* - `buf_proto_lint_test <#buf_proto_lint_test>`_
- Lints .proto files
``buf_proto_breaking_test``
---------------------------
buf_proto_breaking_test
-----------------------
**Note**: This rule is experimental. It may not work correctly!
@ -28,7 +33,7 @@ Checks .proto files for breaking changes
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//buf:repositories.bzl", rules_proto_grpc_buf_repos = "buf_repos")
@ -37,7 +42,7 @@ Checks .proto files for breaking changes
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//buf:defs.bzl", "buf_proto_breaking_test")
@ -56,6 +61,7 @@ Attributes
**********
.. list-table:: Attributes for buf_proto_breaking_test
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -71,7 +77,7 @@ Attributes
* - ``against_input``
- ``label``
- true
- ````
-
- Label of an existing input image file to check against (.json or .bin)
* - ``use_rules``
- ``string_list``
@ -94,8 +100,8 @@ Plugins
- ``@rules_proto_grpc//buf:breaking_plugin``
``buf_proto_lint_test``
-----------------------
buf_proto_lint_test
-------------------
**Note**: This rule is experimental. It may not work correctly!
@ -104,7 +110,7 @@ Lints .proto files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//buf:repositories.bzl", rules_proto_grpc_buf_repos = "buf_repos")
@ -113,7 +119,7 @@ Lints .proto files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//buf:defs.bzl", "buf_proto_lint_test")
@ -168,6 +174,7 @@ Attributes
**********
.. list-table:: Attributes for buf_proto_lint_test
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -178,7 +185,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``use_rules``
- ``string_list``

View File

@ -1,10 +1,15 @@
C rules
=======
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for C
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, C
C
=
Rules for generating C protobuf ``.c`` & ``.h`` files and libraries using `upb <https://github.com/protocolbuffers/upb>`_. Libraries are created with the Bazel native ``cc_library``
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -14,8 +19,8 @@ Rules for generating C protobuf ``.c`` & ``.h`` files and libraries using `upb <
* - `c_proto_library <#c_proto_library>`_
- Generates a C protobuf library using ``cc_library``, with dependencies linked
``c_proto_compile``
-------------------
c_proto_compile
---------------
**Note**: This rule is experimental. It may not work correctly!
@ -24,7 +29,7 @@ Generates C protobuf ``.h`` & ``.c`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//c:repositories.bzl", rules_proto_grpc_c_repos = "c_repos")
@ -37,7 +42,7 @@ Generates C protobuf ``.h`` & ``.c`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//c:defs.bzl", "c_proto_compile")
@ -60,6 +65,7 @@ Attributes
**********
.. list-table:: Attributes for c_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -70,7 +76,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -98,8 +104,8 @@ Plugins
- ``@rules_proto_grpc//c:upb_plugin``
``c_proto_library``
-------------------
c_proto_library
---------------
**Note**: This rule is experimental. It may not work correctly!
@ -108,7 +114,7 @@ Generates a C protobuf library using ``cc_library``, with dependencies linked
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//c:repositories.bzl", rules_proto_grpc_c_repos = "c_repos")
@ -121,7 +127,7 @@ Generates a C protobuf library using ``cc_library``, with dependencies linked
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//c:defs.bzl", "c_proto_library")
@ -140,6 +146,7 @@ Attributes
**********
.. list-table:: Attributes for c_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -150,7 +157,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,3 +1,8 @@
:author: rules_proto_grpc
:description: Changelog for the rules_proto_grpc Bazel rules
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Changelog, Changes, History
Changelog
=========
@ -95,7 +100,7 @@ Switching to non-transitive compilation
In short, replace ``deps`` with ``protos`` on your targets:
.. code-block:: starlark
.. code-block:: python
# Old
python_grpc_library(

View File

@ -1,10 +1,15 @@
C++ rules
=========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for C++
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, C++
C++
===
Rules for generating C++ protobuf and gRPC ``.cc`` & ``.h`` files and libraries using standard Protocol Buffers and gRPC. Libraries are created with the Bazel native ``cc_library``
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating C++ protobuf and gRPC ``.cc`` & ``.h`` files and libraries
* - `cpp_grpc_library <#cpp_grpc_library>`_
- Generates a C++ protobuf and gRPC library using ``cc_library``, with dependencies linked
``cpp_proto_compile``
---------------------
cpp_proto_compile
-----------------
Generates C++ protobuf ``.h`` & ``.cc`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//cpp:repositories.bzl", rules_proto_grpc_cpp_repos = "cpp_repos")
@ -35,7 +40,7 @@ Generates C++ protobuf ``.h`` & ``.cc`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_compile")
@ -58,6 +63,7 @@ Attributes
**********
.. list-table:: Attributes for cpp_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -68,7 +74,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -96,15 +102,15 @@ Plugins
- ``@rules_proto_grpc//cpp:cpp_plugin``
``cpp_grpc_compile``
--------------------
cpp_grpc_compile
----------------
Generates C++ protobuf and gRPC ``.h`` & ``.cc`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//cpp:repositories.bzl", rules_proto_grpc_cpp_repos = "cpp_repos")
@ -117,7 +123,7 @@ Generates C++ protobuf and gRPC ``.h`` & ``.cc`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_grpc_compile")
@ -135,6 +141,7 @@ Attributes
**********
.. list-table:: Attributes for cpp_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -145,7 +152,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -174,15 +181,15 @@ Plugins
- ``@rules_proto_grpc//cpp:cpp_plugin``
- ``@rules_proto_grpc//cpp:grpc_cpp_plugin``
``cpp_proto_library``
---------------------
cpp_proto_library
-----------------
Generates a C++ protobuf library using ``cc_library``, with dependencies linked
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//cpp:repositories.bzl", rules_proto_grpc_cpp_repos = "cpp_repos")
@ -191,7 +198,7 @@ Generates a C++ protobuf library using ``cc_library``, with dependencies linked
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_library")
@ -216,6 +223,7 @@ Attributes
**********
.. list-table:: Attributes for cpp_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -226,7 +234,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -299,15 +307,15 @@ Attributes
- ``None``
- Passed to the ``strip_include_prefix`` attribute of ``cc_library``.
``cpp_grpc_library``
--------------------
cpp_grpc_library
----------------
Generates a C++ protobuf and gRPC library using ``cc_library``, with dependencies linked
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//cpp:repositories.bzl", rules_proto_grpc_cpp_repos = "cpp_repos")
@ -320,7 +328,7 @@ Generates a C++ protobuf and gRPC library using ``cc_library``, with dependencie
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_grpc_library")
@ -339,6 +347,7 @@ Attributes
**********
.. list-table:: Attributes for cpp_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -349,7 +358,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,10 +1,15 @@
C# rules
========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for C#
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, C#
C#
==
Rules for generating C# protobuf and gRPC ``.cs`` files and libraries using standard Protocol Buffers and gRPC. Libraries are created with ``csharp_library`` from `rules_dotnet <https://github.com/bazelbuild/rules_dotnet>`_
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating C# protobuf and gRPC ``.cs`` files and libraries using stan
* - `csharp_grpc_library <#csharp_grpc_library>`_
- Generates a C# protobuf and gRPC library using ``csharp_library`` from ``rules_dotnet``. Note that the library name must end in ``.dll``
``csharp_proto_compile``
------------------------
csharp_proto_compile
--------------------
Generates C# protobuf ``.cs`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//csharp:repositories.bzl", rules_proto_grpc_csharp_repos = "csharp_repos")
@ -53,7 +58,7 @@ Generates C# protobuf ``.cs`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//csharp:defs.bzl", "csharp_proto_compile")
@ -76,6 +81,7 @@ Attributes
**********
.. list-table:: Attributes for csharp_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -86,7 +92,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -114,15 +120,15 @@ Plugins
- ``@rules_proto_grpc//csharp:csharp_plugin``
``csharp_grpc_compile``
-----------------------
csharp_grpc_compile
-------------------
Generates C# protobuf and gRPC ``.cs`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//csharp:repositories.bzl", rules_proto_grpc_csharp_repos = "csharp_repos")
@ -152,7 +158,7 @@ Generates C# protobuf and gRPC ``.cs`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//csharp:defs.bzl", "csharp_grpc_compile")
@ -170,6 +176,7 @@ Attributes
**********
.. list-table:: Attributes for csharp_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -180,7 +187,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -209,15 +216,15 @@ Plugins
- ``@rules_proto_grpc//csharp:csharp_plugin``
- ``@rules_proto_grpc//csharp:grpc_csharp_plugin``
``csharp_proto_library``
------------------------
csharp_proto_library
--------------------
Generates a C# protobuf library using ``csharp_library`` from ``rules_dotnet``. Note that the library name must end in ``.dll``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//csharp:repositories.bzl", rules_proto_grpc_csharp_repos = "csharp_repos")
@ -244,7 +251,7 @@ Generates a C# protobuf library using ``csharp_library`` from ``rules_dotnet``.
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//csharp:defs.bzl", "csharp_proto_library")
@ -269,6 +276,7 @@ Attributes
**********
.. list-table:: Attributes for csharp_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -279,7 +287,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -307,15 +315,15 @@ Attributes
- ``[]``
- List of labels to pass as deps attr to underlying lang_library rule
``csharp_grpc_library``
-----------------------
csharp_grpc_library
-------------------
Generates a C# protobuf and gRPC library using ``csharp_library`` from ``rules_dotnet``. Note that the library name must end in ``.dll``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//csharp:repositories.bzl", rules_proto_grpc_csharp_repos = "csharp_repos")
@ -345,7 +353,7 @@ Generates a C# protobuf and gRPC library using ``csharp_library`` from ``rules_d
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//csharp:defs.bzl", "csharp_grpc_library")
@ -364,6 +372,7 @@ Attributes
**********
.. list-table:: Attributes for csharp_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -374,7 +383,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,12 +1,17 @@
D rules
=======
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for D
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, D
D
=
Rules for generating D protobuf ``.d`` files and libraries using `protobuf-d <https://github.com/dcarp/protobuf-d>`_. Libraries are created with ``d_library`` from `rules_d <https://github.com/bazelbuild/rules_d>`_
**NOTE**: These rules use the protoc-gen-d plugin, which only supports proto3 .proto files.
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -16,15 +21,15 @@ Rules for generating D protobuf ``.d`` files and libraries using `protobuf-d <ht
* - `d_proto_library <#d_proto_library>`_
- Generates a D protobuf library using ``d_library`` from ``rules_d``
``d_proto_compile``
-------------------
d_proto_compile
---------------
Generates D protobuf ``.d`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//d:repositories.bzl", rules_proto_grpc_d_repos = "d_repos")
@ -37,7 +42,7 @@ Generates D protobuf ``.d`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//d:defs.bzl", "d_proto_compile")
@ -60,6 +65,7 @@ Attributes
**********
.. list-table:: Attributes for d_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -70,7 +76,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -98,15 +104,15 @@ Plugins
- ``@rules_proto_grpc//d:d_plugin``
``d_proto_library``
-------------------
d_proto_library
---------------
Generates a D protobuf library using ``d_library`` from ``rules_d``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//d:repositories.bzl", rules_proto_grpc_d_repos = "d_repos")
@ -119,7 +125,7 @@ Generates a D protobuf library using ``d_library`` from ``rules_d``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//d:defs.bzl", "d_proto_library")
@ -144,6 +150,7 @@ Attributes
**********
.. list-table:: Attributes for d_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -154,7 +161,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

121
docs/src/developers.rst Normal file
View File

@ -0,0 +1,121 @@
:author: rules_proto_grpc
:description: Changelog for the rules_proto_grpc Bazel rules
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Developers
Developers
==========
Code Layout
-----------
Each language ``{lang}`` has a top-level subdirectory that contains:
1. ``docs/{lang}.rst``: Generated documentation for the language rules
1. ``{lang}/repositories.bzl``: Macro functions that declare repository rule dependencies for that language
2. ``{lang}/{rule}.bzl``: Rule implementations of the form ``{lang}_{kind}_{type}``, where ``kind`` is one of ``proto|grpc`` and
``type`` is one of ``compile|library``
3. ``{lang}/BUILD.bazel``: ``proto_plugin()`` declarations for the available plugins for the language
4. ``example/{lang}/{rule}/``: Generated ``WORKSPACE`` and ``BUILD.bazel`` demonstrating standalone usage of the rules
5. ``{lang}/example/routeguide/``: Example routeguide example implementation, if possible
Rule Generation
---------------
To help maintain consistency of the rule implementations and documentation, all of the rule implementations are
generated by the tool ``//tools/rulegen``. Changes in the main ``README.rst`` should be placed in
``tools/rulegen/README.header.rst`` or ``tools/rulegen/README.footer.rst```. Changes to generated rules should be put in the
source files (example: ``tools/rulegen/java.go``).
Developing Custom Plugins
-------------------------
Generally, follow the pattern seen in the multiple language examples in this
repository. The basic idea is:
1. Load the plugin rule: ``load("@rules_proto_grpc//:defs.bzl", "proto_plugin")``
2. Define the rule, giving it a ``name``, ``options`` (not mandatory), ``tool`` and ``outputs``. ``tool`` is a label that refers
to the binary executable for the plugin itself
3. Choose your output type (pick one!):
- ``outputs``: A list of strings patterns that predicts the pattern of files generated by the plugin. For plugins that
produce one output file per input proto file
- ``out``: The name of a single output file generated by the plugin
- ``output_directory``: Set to true if your plugin generates files in a non-predictable way. e.g. if the output paths
depend on the service names within the files
4. Create a compilation rule and aspect using the following template:
.. code-block:: python
load("@rules_proto//proto:defs.bzl", "ProtoInfo")
load(
"@rules_proto_grpc//:defs.bzl",
"ProtoLibraryAspectNodeInfo",
"ProtoPluginInfo",
"proto_compile_aspect_attrs",
"proto_compile_aspect_impl",
"proto_compile_attrs",
"proto_compile_impl",
)
# Create aspect
example_aspect = aspect(
implementation = proto_compile_aspect_impl,
provides = [ProtoLibraryAspectNodeInfo],
attr_aspects = ["deps"],
attrs = dict(
proto_compile_aspect_attrs,
_plugins = attr.label_list(
doc = "List of protoc plugins to apply",
providers = [ProtoPluginInfo],
default = [
Label("//<LABEL OF YOUR PLUGIN>"),
],
),
_prefix = attr.string(
doc = "String used to disambiguate aspects when generating outputs",
default = "example_aspect",
),
),
toolchains = ["@rules_proto_grpc//protobuf:toolchain_type"],
)
# Create compile rule to apply aspect
_rule = rule(
implementation = proto_compile_impl,
attrs = dict(
proto_compile_attrs,
protos = attr.label_list(
mandatory = False, # TODO: set to true in 4.0.0 when deps removed below
providers = [ProtoInfo],
doc = "List of labels that provide the ProtoInfo provider (such as proto_library from rules_proto)",
),
deps = attr.label_list(
mandatory = False,
providers = [ProtoInfo, ProtoLibraryAspectNodeInfo],
aspects = [example_aspect],
doc = "DEPRECATED: Use protos attr",
),
_plugins = attr.label_list(
providers = [ProtoPluginInfo],
default = [
Label("//<LABEL OF YOUR PLUGIN>"),
],
doc = "List of protoc plugins to apply",
),
),
toolchains = [str(Label("//protobuf:toolchain_type"))],
)
# Create macro for converting attrs and passing to compile
def example_compile(**kwargs):
_rule(
verbose_string = "{}".format(kwargs.get("verbose", 0)),
**kwargs
)

View File

@ -1,10 +1,15 @@
Documentation rules
===================
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Documentation
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Documentation
Documentation
=============
Rules for generating protobuf Markdown, JSON, HTML or DocBook documentation with `protoc-gen-doc <https://github.com/pseudomuto/protoc-gen-doc>`_
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,8 +23,8 @@ Rules for generating protobuf Markdown, JSON, HTML or DocBook documentation with
* - `doc_markdown_compile <#doc_markdown_compile>`_
- Generates Markdown ``.md`` documentation file
``doc_docbook_compile``
-----------------------
doc_docbook_compile
-------------------
**Note**: This rule is experimental. It may not work correctly!
@ -28,7 +33,7 @@ Generates DocBook ``.xml`` documentation file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
@ -37,7 +42,7 @@ Generates DocBook ``.xml`` documentation file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//doc:defs.bzl", "doc_docbook_compile")
@ -60,6 +65,7 @@ Attributes
**********
.. list-table:: Attributes for doc_docbook_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -70,7 +76,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -98,8 +104,8 @@ Plugins
- ``@rules_proto_grpc//doc:docbook_plugin``
``doc_html_compile``
--------------------
doc_html_compile
----------------
**Note**: This rule is experimental. It may not work correctly!
@ -108,7 +114,7 @@ Generates ``.html`` documentation file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
@ -117,7 +123,7 @@ Generates ``.html`` documentation file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//doc:defs.bzl", "doc_html_compile")
@ -140,6 +146,7 @@ Attributes
**********
.. list-table:: Attributes for doc_html_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -150,7 +157,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -178,8 +185,8 @@ Plugins
- ``@rules_proto_grpc//doc:html_plugin``
``doc_json_compile``
--------------------
doc_json_compile
----------------
**Note**: This rule is experimental. It may not work correctly!
@ -188,7 +195,7 @@ Generates ``.json`` documentation file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
@ -197,7 +204,7 @@ Generates ``.json`` documentation file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//doc:defs.bzl", "doc_json_compile")
@ -220,6 +227,7 @@ Attributes
**********
.. list-table:: Attributes for doc_json_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -230,7 +238,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -258,8 +266,8 @@ Plugins
- ``@rules_proto_grpc//doc:json_plugin``
``doc_markdown_compile``
------------------------
doc_markdown_compile
--------------------
**Note**: This rule is experimental. It may not work correctly!
@ -268,7 +276,7 @@ Generates Markdown ``.md`` documentation file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//doc:repositories.bzl", rules_proto_grpc_doc_repos = "doc_repos")
@ -277,7 +285,7 @@ Generates Markdown ``.md`` documentation file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//doc:defs.bzl", "doc_markdown_compile")
@ -300,6 +308,7 @@ Attributes
**********
.. list-table:: Attributes for doc_markdown_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -310,7 +319,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

106
docs/src/example.rst Normal file
View File

@ -0,0 +1,106 @@
:author: rules_proto_grpc
:description: Example usage for the rules_proto_grpc Bazel rules
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Example, Usage
Example Usage
=============
These steps walk through the actions required to go from a raw ``.proto`` file to a C++ library. Other languages will have
a similar high-level layout.
**Step 1**: Write a Protocol Buffer .proto file (example: ``thing.proto``):
.. code-block:: proto
syntax = "proto3";
package example;
import "google/protobuf/any.proto";
message Thing {
string name = 1;
google.protobuf.Any payload = 2;
}
**Step 2**: Write a ``BAZEL.build`` file with a
`proto_library <https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library>`_ target:
.. code-block:: python
proto_library(
name = "thing_proto",
srcs = ["thing.proto"],
deps = ["@com_google_protobuf//:any_proto"],
)
In this example we have a dependency on a well-known type ``any.proto``, hence the ``proto_library`` to ``proto_library``
dependency (``"@com_google_protobuf//:any_proto"``)
**Step 3**: Add a ``cpp_proto_compile`` target
**Note**: In this example ``thing.proto`` does not include service definitions (gRPC). For protos with services, use the
``cpp_grpc_compile`` rule instead.
.. code-block:: python
# BUILD.bazel
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_compile")
cpp_proto_compile(
name = "cpp_thing_proto",
protos = [":thing_proto"],
)
But wait, before we can build this, we need to load the dependencies necessary for this rule
(see `cpp </cpp>`_):
**Step 4**: Load the workspace macro corresponding to the build rule.
.. code-block:: python
# WORKSPACE
load("@rules_proto_grpc//cpp:repositories.bzl", "cpp_repos")
cpp_repos()
We're now ready to build the target.
**Step 5**: Build it!
.. code-block:: bash
$ bazel build //example/proto:cpp_thing_proto
Target //example/proto:cpp_thing_proto up-to-date:
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc
If we were only interested in the generated files, the ``cpp_grpc_compile`` rule would be fine. However, for
convenience we'd rather have the outputs compiled into a C++ library. To do that, let's change the rule from
``cpp_proto_compile`` to ``cpp_proto_library``:
.. code-block:: python
# BUILD.bazel
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_library")
cpp_proto_library(
name = "cpp_thing_proto",
protos = [":thing_proto"],
)
.. code-block:: bash
$ bazel build //example/proto:cpp_thing_proto
Target //example/proto:cpp_thing_proto up-to-date:
bazel-bin/example/proto/libcpp_thing_proto.a
bazel-bin/example/proto/libcpp_thing_proto.so bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc
This way, we can use ``//example/proto:cpp_thing_proto`` as a dependency of any other ``cc_library`` or ``cc_binary`` target
as per normal.
**Note**: The ``cpp_proto_library`` target implicitly calls ``cpp_proto_compile``, and we can access that rule's by adding
``_pb`` at the end of the target name, like ``bazel build //example/proto:cpp_thing_proto_pb``

View File

@ -1,10 +1,15 @@
Go rules
========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Go
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Go
Go
==
Rules for generating Go protobuf and gRPC ``.go`` files and libraries using `golang/protobuf <https://github.com/golang/protobuf>`_. Libraries are created with ``go_library`` from `rules_go <https://github.com/bazelbuild/rules_go>`_
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating Go protobuf and gRPC ``.go`` files and libraries using `gol
* - `go_grpc_library <#go_grpc_library>`_
- Generates a Go protobuf and gRPC library using ``go_library`` from ``rules_go``
``go_proto_compile``
--------------------
go_proto_compile
----------------
Generates Go protobuf ``.go`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//:repositories.bzl", "bazel_gazelle", "io_bazel_rules_go") # buildifier: disable=same-origin-load
@ -53,7 +58,7 @@ Generates Go protobuf ``.go`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//go:defs.bzl", "go_proto_compile")
@ -76,6 +81,7 @@ Attributes
**********
.. list-table:: Attributes for go_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -86,7 +92,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -114,15 +120,15 @@ Plugins
- ``@rules_proto_grpc//go:go_plugin``
``go_grpc_compile``
-------------------
go_grpc_compile
---------------
Generates Go protobuf and gRPC ``.go`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//:repositories.bzl", "bazel_gazelle", "io_bazel_rules_go") # buildifier: disable=same-origin-load
@ -149,7 +155,7 @@ Generates Go protobuf and gRPC ``.go`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//go:defs.bzl", "go_grpc_compile")
@ -167,6 +173,7 @@ Attributes
**********
.. list-table:: Attributes for go_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -177,7 +184,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -206,15 +213,15 @@ Plugins
- ``@rules_proto_grpc//go:go_plugin``
- ``@rules_proto_grpc//go:grpc_go_plugin``
``go_proto_library``
--------------------
go_proto_library
----------------
Generates a Go protobuf library using ``go_library`` from ``rules_go``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//:repositories.bzl", "bazel_gazelle", "io_bazel_rules_go") # buildifier: disable=same-origin-load
@ -241,7 +248,7 @@ Generates a Go protobuf library using ``go_library`` from ``rules_go``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//go:defs.bzl", "go_proto_library")
@ -259,6 +266,7 @@ Attributes
**********
.. list-table:: Attributes for go_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -269,7 +277,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -302,15 +310,15 @@ Attributes
- ``None``
- Importpath for the generated files
``go_grpc_library``
-------------------
go_grpc_library
---------------
Generates a Go protobuf and gRPC library using ``go_library`` from ``rules_go``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//:repositories.bzl", "bazel_gazelle", "io_bazel_rules_go") # buildifier: disable=same-origin-load
@ -337,7 +345,7 @@ Generates a Go protobuf and gRPC library using ``go_library`` from ``rules_go``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//go:defs.bzl", "go_grpc_library")
@ -354,6 +362,7 @@ Attributes
**********
.. list-table:: Attributes for go_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -364,7 +373,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,8 +1,13 @@
grpc-gateway rules
==================
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for grpc-gateway
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, grpc-gateway
grpc-gateway
============
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -14,15 +19,15 @@ grpc-gateway rules
* - `gateway_grpc_library <#gateway_grpc_library>`_
- Generates grpc-gateway library files
``gateway_grpc_compile``
------------------------
gateway_grpc_compile
--------------------
Generates grpc-gateway ``.go`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//:repositories.bzl", "bazel_gazelle", "io_bazel_rules_go") # buildifier: disable=same-origin-load
@ -53,7 +58,7 @@ Generates grpc-gateway ``.go`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//grpc-gateway:defs.bzl", "gateway_grpc_compile")
@ -66,6 +71,7 @@ Attributes
**********
.. list-table:: Attributes for gateway_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -76,7 +82,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -106,15 +112,15 @@ Plugins
- ``@rules_proto_grpc//go:grpc_go_plugin``
- ``@rules_proto_grpc//go:go_plugin``
``gateway_openapiv2_compile``
-----------------------------
gateway_openapiv2_compile
-------------------------
Generates grpc-gateway OpenAPI v2 ``.json`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//:repositories.bzl", "bazel_gazelle", "io_bazel_rules_go") # buildifier: disable=same-origin-load
@ -145,7 +151,7 @@ Generates grpc-gateway OpenAPI v2 ``.json`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//grpc-gateway:defs.bzl", "gateway_openapiv2_compile")
@ -158,6 +164,7 @@ Attributes
**********
.. list-table:: Attributes for gateway_openapiv2_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -168,7 +175,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -196,15 +203,15 @@ Plugins
- ``@rules_proto_grpc//grpc-gateway:openapiv2_plugin``
``gateway_grpc_library``
------------------------
gateway_grpc_library
--------------------
Generates grpc-gateway library files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//:repositories.bzl", "bazel_gazelle", "io_bazel_rules_go") # buildifier: disable=same-origin-load
@ -235,7 +242,7 @@ Generates grpc-gateway library files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//grpc-gateway:defs.bzl", "gateway_grpc_library")
@ -249,6 +256,7 @@ Attributes
**********
.. list-table:: Attributes for gateway_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -259,7 +267,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

40
docs/src/index.rst Normal file
View File

@ -0,0 +1,40 @@
:author: rules_proto_grpc
:description: Bazel rules for building Protobuf and gRPC code and libraries from proto_library targets
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark
.. include:: ../../README.rst
.. toctree::
:caption: General
:hidden:
Overview <self>
example
developers
transitivity
changelog
GitHub Repo <https://github.com/rules-proto-grpc/rules_proto_grpc>
.. toctree::
:caption: Rules
:hidden:
android
buf
c
cpp
csharp
d
doc
go
grpc-gateway
java
js
objc
php
python
ruby
rust
scala
swift

View File

@ -1,10 +1,15 @@
Java rules
==========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Java
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Java
Java
====
Rules for generating Java protobuf and gRPC ``.jar`` files and libraries using standard Protocol Buffers and `gRPC-Java <https://github.com/grpc/grpc-java>`_. Libraries are created with the Bazel native ``java_library``
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating Java protobuf and gRPC ``.jar`` files and libraries using s
* - `java_grpc_library <#java_grpc_library>`_
- Generates a Java protobuf and gRPC library using ``java_library``
``java_proto_compile``
----------------------
java_proto_compile
------------------
Generates a Java protobuf srcjar file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//java:repositories.bzl", rules_proto_grpc_java_repos = "java_repos")
@ -35,7 +40,7 @@ Generates a Java protobuf srcjar file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//java:defs.bzl", "java_proto_compile")
@ -58,6 +63,7 @@ Attributes
**********
.. list-table:: Attributes for java_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -68,7 +74,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -96,15 +102,15 @@ Plugins
- ``@rules_proto_grpc//java:java_plugin``
``java_grpc_compile``
---------------------
java_grpc_compile
-----------------
Generates a Java protobuf and gRPC srcjar file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//java:repositories.bzl", rules_proto_grpc_java_repos = "java_repos")
@ -113,7 +119,7 @@ Generates a Java protobuf and gRPC srcjar file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//java:defs.bzl", "java_grpc_compile")
@ -131,6 +137,7 @@ Attributes
**********
.. list-table:: Attributes for java_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -141,7 +148,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -170,15 +177,15 @@ Plugins
- ``@rules_proto_grpc//java:java_plugin``
- ``@rules_proto_grpc//java:grpc_java_plugin``
``java_proto_library``
----------------------
java_proto_library
------------------
Generates a Java protobuf library using ``java_library``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//java:repositories.bzl", rules_proto_grpc_java_repos = "java_repos")
@ -187,7 +194,7 @@ Generates a Java protobuf library using ``java_library``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//java:defs.bzl", "java_proto_library")
@ -212,6 +219,7 @@ Attributes
**********
.. list-table:: Attributes for java_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -222,7 +230,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -255,15 +263,15 @@ Attributes
- ``[]``
- List of labels to pass as exports attr to underlying lang_library rule
``java_grpc_library``
---------------------
java_grpc_library
-----------------
Generates a Java protobuf and gRPC library using ``java_library``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//java:repositories.bzl", rules_proto_grpc_java_repos = "java_repos")
@ -290,7 +298,7 @@ Generates a Java protobuf and gRPC library using ``java_library``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//java:defs.bzl", "java_grpc_library")
@ -309,6 +317,7 @@ Attributes
**********
.. list-table:: Attributes for java_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -319,7 +328,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,5 +1,10 @@
JavaScript rules
================
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for JavaScript
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, JavaScript
JavaScript
==========
Rules for generating JavaScript protobuf, gRPC-node and gRPC-Web ``.js`` and ``.d.ts`` files using standard Protocol Buffers and gRPC.
@ -17,7 +22,7 @@ Rules for generating JavaScript protobuf, gRPC-node and gRPC-Web ``.js`` and ``.
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -35,15 +40,15 @@ Rules for generating JavaScript protobuf, gRPC-node and gRPC-Web ``.js`` and ``.
* - `js_grpc_web_library <#js_grpc_web_library>`_
- Generates a JavaScript protobuf + gRPC-Web library using ``js_library`` from ``rules_nodejs``
``js_proto_compile``
--------------------
js_proto_compile
----------------
Generates JavaScript protobuf ``.js`` and ``.d.ts`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:repositories.bzl", rules_proto_grpc_js_repos = "js_repos")
@ -60,7 +65,7 @@ Generates JavaScript protobuf ``.js`` and ``.d.ts`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:defs.bzl", "js_proto_compile")
@ -83,6 +88,7 @@ Attributes
**********
.. list-table:: Attributes for js_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -93,7 +99,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -122,15 +128,15 @@ Plugins
- ``@rules_proto_grpc//js:js_plugin``
- ``@rules_proto_grpc//js:ts_plugin``
``js_grpc_node_compile``
------------------------
js_grpc_node_compile
--------------------
Generates JavaScript protobuf and gRPC-node ``.js`` and ``.d.ts`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:repositories.bzl", rules_proto_grpc_js_repos = "js_repos")
@ -147,7 +153,7 @@ Generates JavaScript protobuf and gRPC-node ``.js`` and ``.d.ts`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:defs.bzl", "js_grpc_node_compile")
@ -165,6 +171,7 @@ Attributes
**********
.. list-table:: Attributes for js_grpc_node_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -175,7 +182,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -206,15 +213,15 @@ Plugins
- ``@rules_proto_grpc//js:grpc_node_plugin``
- ``@rules_proto_grpc//js:grpc_node_ts_plugin``
``js_grpc_web_compile``
-----------------------
js_grpc_web_compile
-------------------
Generates JavaScript protobuf and gRPC-Web ``.js`` and ``.d.ts`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:repositories.bzl", rules_proto_grpc_js_repos = "js_repos")
@ -231,7 +238,7 @@ Generates JavaScript protobuf and gRPC-Web ``.js`` and ``.d.ts`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:defs.bzl", "js_grpc_web_compile")
@ -249,6 +256,7 @@ Attributes
**********
.. list-table:: Attributes for js_grpc_web_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -259,7 +267,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -289,15 +297,15 @@ Plugins
- ``@rules_proto_grpc//js:ts_plugin``
- ``@rules_proto_grpc//js:grpc_web_js_plugin``
``js_proto_library``
--------------------
js_proto_library
----------------
Generates a JavaScript protobuf library using ``js_library`` from ``rules_nodejs``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:repositories.bzl", rules_proto_grpc_js_repos = "js_repos")
@ -314,7 +322,7 @@ Generates a JavaScript protobuf library using ``js_library`` from ``rules_nodejs
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:defs.bzl", "js_proto_library")
@ -339,6 +347,7 @@ Attributes
**********
.. list-table:: Attributes for js_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -349,7 +358,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -382,15 +391,15 @@ Attributes
- ``@npm``
- The repository to load the dependencies from, if you don't use ``@npm``
``js_grpc_node_library``
------------------------
js_grpc_node_library
--------------------
Generates a Node.js protobuf + gRPC-node library using ``js_library`` from ``rules_nodejs``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:repositories.bzl", rules_proto_grpc_js_repos = "js_repos")
@ -407,7 +416,7 @@ Generates a Node.js protobuf + gRPC-node library using ``js_library`` from ``rul
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:defs.bzl", "js_grpc_node_library")
@ -426,6 +435,7 @@ Attributes
**********
.. list-table:: Attributes for js_grpc_node_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -436,7 +446,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -469,15 +479,15 @@ Attributes
- ``@npm``
- The repository to load the dependencies from, if you don't use ``@npm``
``js_grpc_web_library``
-----------------------
js_grpc_web_library
-------------------
Generates a JavaScript protobuf + gRPC-Web library using ``js_library`` from ``rules_nodejs``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:repositories.bzl", rules_proto_grpc_js_repos = "js_repos")
@ -494,7 +504,7 @@ Generates a JavaScript protobuf + gRPC-Web library using ``js_library`` from ``r
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//js:defs.bzl", "js_grpc_web_library")
@ -513,6 +523,7 @@ Attributes
**********
.. list-table:: Attributes for js_grpc_web_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -523,7 +534,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,10 +1,15 @@
Objective-C rules
=================
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Objective-C
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Objective-C
Objective-C
===========
Rules for generating Objective-C protobuf and gRPC ``.m`` & ``.h`` files and libraries using standard Protocol Buffers and gRPC. Libraries are created with the Bazel native ``objc_library``
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating Objective-C protobuf and gRPC ``.m`` & ``.h`` files and lib
* - `objc_grpc_library <#objc_grpc_library>`_
- Generates an Objective-C protobuf and gRPC library using ``objc_library``
``objc_proto_compile``
----------------------
objc_proto_compile
------------------
Generates Objective-C protobuf ``.m`` & ``.h`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//objc:repositories.bzl", rules_proto_grpc_objc_repos = "objc_repos")
@ -35,7 +40,7 @@ Generates Objective-C protobuf ``.m`` & ``.h`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//objc:defs.bzl", "objc_proto_compile")
@ -58,6 +63,7 @@ Attributes
**********
.. list-table:: Attributes for objc_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -68,7 +74,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -96,15 +102,15 @@ Plugins
- ``@rules_proto_grpc//objc:objc_plugin``
``objc_grpc_compile``
---------------------
objc_grpc_compile
-----------------
Generates Objective-C protobuf and gRPC ``.m`` & ``.h`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//objc:repositories.bzl", rules_proto_grpc_objc_repos = "objc_repos")
@ -117,7 +123,7 @@ Generates Objective-C protobuf and gRPC ``.m`` & ``.h`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//objc:defs.bzl", "objc_grpc_compile")
@ -135,6 +141,7 @@ Attributes
**********
.. list-table:: Attributes for objc_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -145,7 +152,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -174,15 +181,15 @@ Plugins
- ``@rules_proto_grpc//objc:objc_plugin``
- ``@rules_proto_grpc//objc:grpc_objc_plugin``
``objc_proto_library``
----------------------
objc_proto_library
------------------
Generates an Objective-C protobuf library using ``objc_library``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//objc:repositories.bzl", rules_proto_grpc_objc_repos = "objc_repos")
@ -191,7 +198,7 @@ Generates an Objective-C protobuf library using ``objc_library``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//objc:defs.bzl", "objc_proto_library")
@ -216,6 +223,7 @@ Attributes
**********
.. list-table:: Attributes for objc_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -226,7 +234,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -299,8 +307,8 @@ Attributes
- ``None``
- Passed to the ``strip_include_prefix`` attribute of ``cc_library``.
``objc_grpc_library``
---------------------
objc_grpc_library
-----------------
**Note**: This rule is experimental. It may not work correctly!
@ -309,7 +317,7 @@ Generates an Objective-C protobuf and gRPC library using ``objc_library``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//objc:repositories.bzl", rules_proto_grpc_objc_repos = "objc_repos")
@ -322,7 +330,7 @@ Generates an Objective-C protobuf and gRPC library using ``objc_library``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//objc:defs.bzl", "objc_grpc_library")
@ -341,6 +349,7 @@ Attributes
**********
.. list-table:: Attributes for objc_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -351,7 +360,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,10 +1,15 @@
PHP rules
=========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for PHP
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, PHP
PHP
===
Rules for generating PHP protobuf and gRPC ``.php`` files and libraries using standard Protocol Buffers and gRPC
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -14,15 +19,15 @@ Rules for generating PHP protobuf and gRPC ``.php`` files and libraries using st
* - `php_grpc_compile <#php_grpc_compile>`_
- Generates PHP protobuf and gRPC ``.php`` files
``php_proto_compile``
---------------------
php_proto_compile
-----------------
Generates PHP protobuf ``.php`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//php:repositories.bzl", rules_proto_grpc_php_repos = "php_repos")
@ -31,7 +36,7 @@ Generates PHP protobuf ``.php`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//php:defs.bzl", "php_proto_compile")
@ -54,6 +59,7 @@ Attributes
**********
.. list-table:: Attributes for php_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -64,7 +70,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -92,15 +98,15 @@ Plugins
- ``@rules_proto_grpc//php:php_plugin``
``php_grpc_compile``
--------------------
php_grpc_compile
----------------
Generates PHP protobuf and gRPC ``.php`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//php:repositories.bzl", rules_proto_grpc_php_repos = "php_repos")
@ -113,7 +119,7 @@ Generates PHP protobuf and gRPC ``.php`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//php:defs.bzl", "php_grpc_compile")
@ -131,6 +137,7 @@ Attributes
**********
.. list-table:: Attributes for php_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -141,7 +148,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,12 +1,17 @@
Python rules
============
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Python
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Python
Python
======
Rules for generating Python protobuf and gRPC ``.py`` files and libraries using standard Protocol Buffers and gRPC or `grpclib <https://github.com/vmagamedov/grpclib>`_. Libraries are created with ``py_library`` from ``rules_python``. To use the fast C++ Protobuf implementation, you can add ``--define=use_fast_cpp_protos=true`` to your build, but this requires you setup the path to your Python headers.
**Note**: On Windows, the path to Python for ``pip_install`` may need updating to ``Python.exe``, depending on your install.
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -24,15 +29,15 @@ Rules for generating Python protobuf and gRPC ``.py`` files and libraries using
* - `python_grpclib_library <#python_grpclib_library>`_
- Generates a Python protobuf and grpclib library using ``py_library`` from ``rules_python`` (supports Python 3 only)
``python_proto_compile``
------------------------
python_proto_compile
--------------------
Generates Python protobuf ``.py`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos")
@ -41,7 +46,7 @@ Generates Python protobuf ``.py`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:defs.bzl", "python_proto_compile")
@ -64,6 +69,7 @@ Attributes
**********
.. list-table:: Attributes for python_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -74,7 +80,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -102,15 +108,15 @@ Plugins
- ``@rules_proto_grpc//python:python_plugin``
``python_grpc_compile``
-----------------------
python_grpc_compile
-------------------
Generates Python protobuf and gRPC ``.py`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos")
@ -123,7 +129,7 @@ Generates Python protobuf and gRPC ``.py`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:defs.bzl", "python_grpc_compile")
@ -141,6 +147,7 @@ Attributes
**********
.. list-table:: Attributes for python_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -151,7 +158,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -180,15 +187,15 @@ Plugins
- ``@rules_proto_grpc//python:python_plugin``
- ``@rules_proto_grpc//python:grpc_python_plugin``
``python_grpclib_compile``
--------------------------
python_grpclib_compile
----------------------
Generates Python protobuf and grpclib ``.py`` files (supports Python 3 only)
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos")
@ -209,7 +216,7 @@ Generates Python protobuf and grpclib ``.py`` files (supports Python 3 only)
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:defs.bzl", "python_grpclib_compile")
@ -227,6 +234,7 @@ Attributes
**********
.. list-table:: Attributes for python_grpclib_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -237,7 +245,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -266,15 +274,15 @@ Plugins
- ``@rules_proto_grpc//python:python_plugin``
- ``@rules_proto_grpc//python:grpclib_python_plugin``
``python_proto_library``
------------------------
python_proto_library
--------------------
Generates a Python protobuf library using ``py_library`` from ``rules_python``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos")
@ -283,7 +291,7 @@ Generates a Python protobuf library using ``py_library`` from ``rules_python``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:defs.bzl", "python_proto_library")
@ -308,6 +316,7 @@ Attributes
**********
.. list-table:: Attributes for python_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -318,7 +327,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -346,15 +355,15 @@ Attributes
- ``[]``
- List of labels to pass as deps attr to underlying lang_library rule
``python_grpc_library``
-----------------------
python_grpc_library
-------------------
Generates a Python protobuf and gRPC library using ``py_library`` from ``rules_python``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos")
@ -367,7 +376,7 @@ Generates a Python protobuf and gRPC library using ``py_library`` from ``rules_p
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:defs.bzl", "python_grpc_library")
@ -386,6 +395,7 @@ Attributes
**********
.. list-table:: Attributes for python_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -396,7 +406,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -424,15 +434,15 @@ Attributes
- ``[]``
- List of labels to pass as deps attr to underlying lang_library rule
``python_grpclib_library``
--------------------------
python_grpclib_library
----------------------
Generates a Python protobuf and grpclib library using ``py_library`` from ``rules_python`` (supports Python 3 only)
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:repositories.bzl", rules_proto_grpc_python_repos = "python_repos")
@ -453,7 +463,7 @@ Generates a Python protobuf and grpclib library using ``py_library`` from ``rule
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//python:defs.bzl", "python_grpclib_library")
@ -472,6 +482,7 @@ Attributes
**********
.. list-table:: Attributes for python_grpclib_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -482,7 +493,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,10 +1,15 @@
Ruby rules
==========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Ruby
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Ruby
Ruby
====
Rules for generating Ruby protobuf and gRPC ``.rb`` files and libraries using standard Protocol Buffers and gRPC. Libraries are created with ``ruby_library`` from `rules_ruby <https://github.com/bazelruby/rules_ruby>`_
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating Ruby protobuf and gRPC ``.rb`` files and libraries using st
* - `ruby_grpc_library <#ruby_grpc_library>`_
- Generates a Ruby protobuf and gRPC library using ``ruby_library`` from ``rules_ruby``
``ruby_proto_compile``
----------------------
ruby_proto_compile
------------------
Generates Ruby protobuf ``.rb`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//ruby:repositories.bzl", rules_proto_grpc_ruby_repos = "ruby_repos")
@ -49,7 +54,7 @@ Generates Ruby protobuf ``.rb`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//ruby:defs.bzl", "ruby_proto_compile")
@ -72,6 +77,7 @@ Attributes
**********
.. list-table:: Attributes for ruby_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -82,7 +88,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -110,15 +116,15 @@ Plugins
- ``@rules_proto_grpc//ruby:ruby_plugin``
``ruby_grpc_compile``
---------------------
ruby_grpc_compile
-----------------
Generates Ruby protobuf and gRPC ``.rb`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//ruby:repositories.bzl", rules_proto_grpc_ruby_repos = "ruby_repos")
@ -145,7 +151,7 @@ Generates Ruby protobuf and gRPC ``.rb`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//ruby:defs.bzl", "ruby_grpc_compile")
@ -163,6 +169,7 @@ Attributes
**********
.. list-table:: Attributes for ruby_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -173,7 +180,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -202,15 +209,15 @@ Plugins
- ``@rules_proto_grpc//ruby:ruby_plugin``
- ``@rules_proto_grpc//ruby:grpc_ruby_plugin``
``ruby_proto_library``
----------------------
ruby_proto_library
------------------
Generates a Ruby protobuf library using ``ruby_library`` from ``rules_ruby``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//ruby:repositories.bzl", rules_proto_grpc_ruby_repos = "ruby_repos")
@ -233,7 +240,7 @@ Generates a Ruby protobuf library using ``ruby_library`` from ``rules_ruby``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//ruby:defs.bzl", "ruby_proto_library")
@ -258,6 +265,7 @@ Attributes
**********
.. list-table:: Attributes for ruby_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -268,7 +276,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -296,15 +304,15 @@ Attributes
- ``[]``
- List of labels to pass as deps attr to underlying lang_library rule
``ruby_grpc_library``
---------------------
ruby_grpc_library
-----------------
Generates a Ruby protobuf and gRPC library using ``ruby_library`` from ``rules_ruby``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//ruby:repositories.bzl", rules_proto_grpc_ruby_repos = "ruby_repos")
@ -331,7 +339,7 @@ Generates a Ruby protobuf and gRPC library using ``ruby_library`` from ``rules_r
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//ruby:defs.bzl", "ruby_grpc_library")
@ -350,6 +358,7 @@ Attributes
**********
.. list-table:: Attributes for ruby_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -360,7 +369,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,10 +1,15 @@
Rust rules
==========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Rust
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Rust
Rust
====
Rules for generating Rust protobuf and gRPC ``.rs`` files and libraries using `rust-protobuf <https://github.com/stepancheg/rust-protobuf> and `grpc-rs <https://github.com/tikv/grpc-rs>`_. Libraries are created with ``rust_library`` from `rules_rust <https://github.com/bazelbuild/rules_rust>`_.
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating Rust protobuf and gRPC ``.rs`` files and libraries using `r
* - `rust_grpc_library <#rust_grpc_library>`_
- Generates a Rust protobuf and gRPC library using ``rust_library`` from ``rules_rust``
``rust_proto_compile``
----------------------
rust_proto_compile
------------------
Generates Rust protobuf ``.rs`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//rust:repositories.bzl", rules_proto_grpc_rust_repos = "rust_repos")
@ -43,7 +48,7 @@ Generates Rust protobuf ``.rs`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//rust:defs.bzl", "rust_proto_compile")
@ -66,6 +71,7 @@ Attributes
**********
.. list-table:: Attributes for rust_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -76,7 +82,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -104,15 +110,15 @@ Plugins
- ``@rules_proto_grpc//rust:rust_plugin``
``rust_grpc_compile``
---------------------
rust_grpc_compile
-----------------
Generates Rust protobuf and gRPC ``.rs`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//rust:repositories.bzl", rules_proto_grpc_rust_repos = "rust_repos")
@ -129,7 +135,7 @@ Generates Rust protobuf and gRPC ``.rs`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//rust:defs.bzl", "rust_grpc_compile")
@ -147,6 +153,7 @@ Attributes
**********
.. list-table:: Attributes for rust_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -157,7 +164,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -186,15 +193,15 @@ Plugins
- ``@rules_proto_grpc//rust:rust_plugin``
- ``@rules_proto_grpc//rust:grpc_rust_plugin``
``rust_proto_library``
----------------------
rust_proto_library
------------------
Generates a Rust protobuf library using ``rust_library`` from ``rules_rust``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//rust:repositories.bzl", rules_proto_grpc_rust_repos = "rust_repos")
@ -211,7 +218,7 @@ Generates a Rust protobuf library using ``rust_library`` from ``rules_rust``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//rust:defs.bzl", "rust_proto_library")
@ -228,6 +235,7 @@ Attributes
**********
.. list-table:: Attributes for rust_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -238,7 +246,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -266,15 +274,15 @@ Attributes
- ``[]``
- List of labels to pass as deps attr to underlying lang_library rule
``rust_grpc_library``
---------------------
rust_grpc_library
-----------------
Generates a Rust protobuf and gRPC library using ``rust_library`` from ``rules_rust``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//rust:repositories.bzl", rules_proto_grpc_rust_repos = "rust_repos")
@ -291,7 +299,7 @@ Generates a Rust protobuf and gRPC library using ``rust_library`` from ``rules_r
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//rust:defs.bzl", "rust_grpc_library")
@ -307,6 +315,7 @@ Attributes
**********
.. list-table:: Attributes for rust_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -317,7 +326,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,10 +1,15 @@
Scala rules
===========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Scala
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Scala
Scala
=====
Rules for generating Scala protobuf and gRPC ``.jar`` files and libraries using `ScalaPB <https://github.com/scalapb/ScalaPB>`_. Libraries are created with ``scala_library`` from `rules_scala <https://github.com/bazelbuild/rules_scala>`_
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating Scala protobuf and gRPC ``.jar`` files and libraries using
* - `scala_grpc_library <#scala_grpc_library>`_
- Generates a Scala protobuf and gRPC library using ``scala_library`` from ``rules_scala``
``scala_proto_compile``
-----------------------
scala_proto_compile
-------------------
Generates a Scala protobuf ``.jar`` file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//scala:repositories.bzl", rules_proto_grpc_scala_repos = "scala_repos")
@ -51,7 +56,7 @@ Generates a Scala protobuf ``.jar`` file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//scala:defs.bzl", "scala_proto_compile")
@ -74,6 +79,7 @@ Attributes
**********
.. list-table:: Attributes for scala_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -84,7 +90,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -112,15 +118,15 @@ Plugins
- ``@rules_proto_grpc//scala:scala_plugin``
``scala_grpc_compile``
----------------------
scala_grpc_compile
------------------
Generates Scala protobuf and gRPC ``.jar`` file
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//scala:repositories.bzl", rules_proto_grpc_scala_repos = "scala_repos")
@ -149,7 +155,7 @@ Generates Scala protobuf and gRPC ``.jar`` file
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//scala:defs.bzl", "scala_grpc_compile")
@ -167,6 +173,7 @@ Attributes
**********
.. list-table:: Attributes for scala_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -177,7 +184,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -205,15 +212,15 @@ Plugins
- ``@rules_proto_grpc//scala:grpc_scala_plugin``
``scala_proto_library``
-----------------------
scala_proto_library
-------------------
Generates a Scala protobuf library using ``scala_library`` from ``rules_scala``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//scala:repositories.bzl", rules_proto_grpc_scala_repos = "scala_repos")
@ -238,7 +245,7 @@ Generates a Scala protobuf library using ``scala_library`` from ``rules_scala``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//scala:defs.bzl", "scala_proto_library")
@ -263,6 +270,7 @@ Attributes
**********
.. list-table:: Attributes for scala_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -273,7 +281,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -306,15 +314,15 @@ Attributes
- ``[]``
- List of labels to pass as exports attr to underlying lang_library rule
``scala_grpc_library``
----------------------
scala_grpc_library
------------------
Generates a Scala protobuf and gRPC library using ``scala_library`` from ``rules_scala``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//scala:repositories.bzl", rules_proto_grpc_scala_repos = "scala_repos")
@ -343,7 +351,7 @@ Generates a Scala protobuf and gRPC library using ``scala_library`` from ``rules
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//scala:defs.bzl", "scala_grpc_library")
@ -362,6 +370,7 @@ Attributes
**********
.. list-table:: Attributes for scala_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -372,7 +381,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``

View File

@ -1,10 +1,15 @@
Swift rules
===========
:author: rules_proto_grpc
:description: rules_proto_grpc Bazel rules for Swift
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Swift
Swift
=====
Rules for generating Swift protobuf and gRPC ``.swift`` files and libraries using `Swift Protobuf <https://github.com/apple/swift-protobuf>`_ and `Swift gRPC <https://github.com/grpc/grpc-swift>`_
.. list-table:: Rules
:widths: 1 1
:widths: 1 2
:header-rows: 1
* - Rule
@ -18,15 +23,15 @@ Rules for generating Swift protobuf and gRPC ``.swift`` files and libraries usin
* - `swift_grpc_library <#swift_grpc_library>`_
- Generates a Swift protobuf and gRPC library using ``swift_library`` from ``rules_swift``
``swift_proto_compile``
-----------------------
swift_proto_compile
-------------------
Generates Swift protobuf ``.swift`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//swift:repositories.bzl", rules_proto_grpc_swift_repos = "swift_repos")
@ -42,7 +47,7 @@ Generates Swift protobuf ``.swift`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//swift:defs.bzl", "swift_proto_compile")
@ -65,6 +70,7 @@ Attributes
**********
.. list-table:: Attributes for swift_proto_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -75,7 +81,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -103,15 +109,15 @@ Plugins
- ``@rules_proto_grpc//swift:swift_plugin``
``swift_grpc_compile``
----------------------
swift_grpc_compile
------------------
Generates Swift protobuf and gRPC ``.swift`` files
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//swift:repositories.bzl", rules_proto_grpc_swift_repos = "swift_repos")
@ -127,7 +133,7 @@ Generates Swift protobuf and gRPC ``.swift`` files
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//swift:defs.bzl", "swift_grpc_compile")
@ -145,6 +151,7 @@ Attributes
**********
.. list-table:: Attributes for swift_grpc_compile
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -155,7 +162,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -184,15 +191,15 @@ Plugins
- ``@rules_proto_grpc//swift:swift_plugin``
- ``@rules_proto_grpc//swift:grpc_swift_plugin``
``swift_proto_library``
-----------------------
swift_proto_library
-------------------
Generates a Swift protobuf library using ``swift_library`` from ``rules_swift``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//swift:repositories.bzl", rules_proto_grpc_swift_repos = "swift_repos")
@ -208,7 +215,7 @@ Generates a Swift protobuf library using ``swift_library`` from ``rules_swift``
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//swift:defs.bzl", "swift_proto_library")
@ -225,6 +232,7 @@ Attributes
**********
.. list-table:: Attributes for swift_proto_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -235,7 +243,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -265,18 +273,18 @@ Attributes
* - ``module_name``
- ``string``
- false
- ````
-
- The name of the Swift module being built.
``swift_grpc_library``
----------------------
swift_grpc_library
------------------
Generates a Swift protobuf and gRPC library using ``swift_library`` from ``rules_swift``
``WORKSPACE``
*************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//swift:repositories.bzl", rules_proto_grpc_swift_repos = "swift_repos")
@ -292,7 +300,7 @@ Generates a Swift protobuf and gRPC library using ``swift_library`` from ``rules
``BUILD.bazel``
***************
.. code-block:: starlark
.. code-block:: python
load("@rules_proto_grpc//swift:defs.bzl", "swift_grpc_library")
@ -308,6 +316,7 @@ Attributes
**********
.. list-table:: Attributes for swift_grpc_library
:widths: 1 1 1 1 4
:header-rows: 1
* - Name
@ -318,7 +327,7 @@ Attributes
* - ``protos``
- ``label_list``
- true
- ````
-
- List of labels that provide the ``ProtoInfo`` provider (such as ``proto_library`` from ``rules_proto``)
* - ``options``
- ``string_list_dict``
@ -348,5 +357,5 @@ Attributes
* - ``module_name``
- ``string``
- false
- ````
-
- The name of the Swift module being built.

View File

@ -1,4 +1,10 @@
# Transitivity
:author: rules_proto_grpc
:description: Transitivity changes for rules_proto_grpc Bazel rules
:keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, Transitivity, Aspect
Transitivity
============
In previous versions of rules_proto_grpc, the compilation aspect would compile and aggregate all dependent .proto files
from any top level target. In hindsight, this was not the correct behaviour and led to many bugs, since you may end up
@ -12,32 +18,33 @@ duplicate files in the output binaries.
Therefore, in this release of rules_proto_grpc, there is now a recommedned option to bundle only the direct proto
dependencies into the libraries, without including the compiled transitive proto files. This is done by replacing the
`deps` attr on `lang_{proto|grpc}_{compile|library}` with the `protos` attr. Since this would be a substantial breaking
``deps`` attr on ``lang_{proto|grpc}_{compile|library}`` with the ``protos`` attr. Since this would be a substantial breaking
change to drop at once on a large project, the new behaviour is opt-in in 3.0.0 and the old method continues to work
throughout the 3.x.x release cycle. Rules using the previous deps attr will have a warning written to console to signify
that your library may be bundling more than expect and should switch attr.
As an additional benefit of this change, we can now support passing arbitrary per-target rules to protoc through the new
`options` attr of the rules, which was a much sought after change that was impossible in the aspect based compilation.
``options`` attr of the rules, which was a much sought after change that was impossible in the aspect based compilation.
### Switching to non-transitive compilation
Switching to non-transitive compilation
---------------------------------------
In short, replace `deps` with `protos` on your targets:
In short, replace ``deps`` with ``protos`` on your targets:
```starlark
# Old
python_grpc_library(
.. code-block:: python
# Old
python_grpc_library(
name = "routeguide",
deps = ["//example/proto:routeguide_proto"],
)
)
# New
python_grpc_library(
# New
python_grpc_library(
name = "routeguide",
protos = ["//example/proto:routeguide_proto"],
)
```
)
In applying the above change, you may discover that you were inheriting dependencies transitively and that your builds
now fail. In such cases, you should add a `lang_{proto|grpc}_{compile|library}` target for those proto files and
now fail. In such cases, you should add a ``lang_{proto|grpc}_{compile|library}`` target for those proto files and
depend on it explicitly from the relevant top level binaries/libraries.

42
docs/templates/base.html vendored Normal file
View File

@ -0,0 +1,42 @@
{% extends "!base.html" %}
{% block extrahead %}
<!-- Metadata -->
{%- if meta %}
{%- for tag in ('description', 'author', 'keywords') %}
{%- if tag in meta %}
<meta name="{{ tag }}" content="{{ meta[tag].replace('\n', ' ')|e }}">
{%- endif %}
{%- endfor %}
{%- endif %}
<!-- Icons -->
{%- if favicon %}
<link rel="shortcut icon" href="{{ pathto('_static/' + favicon, 1)|e }}"/>
{%- endif %}
{%- if icon_png %}
<link rel="apple-touch-icon" href="{{ pathto('_static/' + icon_png, 1)|e }}">
{%- endif %}
<!-- Canonical URL -->
{%- if baseurl %}
<link rel="canonical" href="{{ baseurl.rstrip('/')|e }}/{{ pagename|e }}.html"/>
{%- endif %}
<!-- Open Graph -->
{%- if baseurl %}
<meta property="og:url" content="{{ baseurl.rstrip('/')|e }}/{{ pagename|e }}.html" />
{%- endif %}
<meta property="og:title" content="{{ title|striptags|e }}{{ titlesuffix }}" />
{%- if baseurl and icon_png %}
<meta property="og:image" content="{{ (baseurl.rstrip('/') + '/_static/' + icon_png)|e }}" />
{%- endif %}
<meta property="og:type" content="website">
{%- if meta and 'description' in meta %}
<meta property="og:description" content="{{ meta['description'].replace('\n', ' ') }}">
{%- endif %}
<script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": ""}'></script>
{{ super() }}
{% endblock %}

View File

@ -1,224 +1,3 @@
Example Usage
-------------
These steps walk through the actions required to go from a raw ``.proto`` file to a C++ library. Other languages will have
a similar high-level layout.
**Step 1**: Write a Protocol Buffer .proto file (example: ``thing.proto``):
.. code-block:: proto
syntax = "proto3";
package example;
import "google/protobuf/any.proto";
message Thing {
string name = 1;
google.protobuf.Any payload = 2;
}
**Step 2**: Write a ``BAZEL.build`` file with a
`proto_library <https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library>`_ target:
.. code-block:: starlark
proto_library(
name = "thing_proto",
srcs = ["thing.proto"],
deps = ["@com_google_protobuf//:any_proto"],
)
In this example we have a dependency on a well-known type ``any.proto``, hence the ``proto_library`` to ``proto_library``
dependency (``"@com_google_protobuf//:any_proto"``)
**Step 3**: Add a ``cpp_proto_compile`` target
**Note**: In this example ``thing.proto`` does not include service definitions (gRPC). For protos with services, use the
``cpp_grpc_compile`` rule instead.
.. code-block:: starlark
# BUILD.bazel
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_compile")
cpp_proto_compile(
name = "cpp_thing_proto",
protos = [":thing_proto"],
)
But wait, before we can build this, we need to load the dependencies necessary for this rule
(see `cpp </cpp>`_):
**Step 4**: Load the workspace macro corresponding to the build rule.
.. code-block:: starlark
# WORKSPACE
load("@rules_proto_grpc//cpp:repositories.bzl", "cpp_repos")
cpp_repos()
We're now ready to build the target.
**Step 5**: Build it!
.. code-block:: bash
$ bazel build //example/proto:cpp_thing_proto
Target //example/proto:cpp_thing_proto up-to-date:
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc
If we were only interested in the generated files, the ``cpp_grpc_compile`` rule would be fine. However, for
convenience we'd rather have the outputs compiled into a C++ library. To do that, let's change the rule from
``cpp_proto_compile`` to ``cpp_proto_library``:
.. code-block:: starlark
# BUILD.bazel
load("@rules_proto_grpc//cpp:defs.bzl", "cpp_proto_library")
cpp_proto_library(
name = "cpp_thing_proto",
protos = [":thing_proto"],
)
.. code-block:: bash
$ bazel build //example/proto:cpp_thing_proto
Target //example/proto:cpp_thing_proto up-to-date:
bazel-bin/example/proto/libcpp_thing_proto.a
bazel-bin/example/proto/libcpp_thing_proto.so bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.h
bazel-genfiles/example/proto/cpp_thing_proto/example/proto/thing.pb.cc
This way, we can use ``//example/proto:cpp_thing_proto`` as a dependency of any other ``cc_library`` or ``cc_binary`` target
as per normal.
**Note**: The ``cpp_proto_library`` target implicitly calls ``cpp_proto_compile``, and we can access that rule's by adding
``_pb`` at the end of the target name, like ``bazel build //example/proto:cpp_thing_proto_pb``
Developers
----------
Code Layout
***********
Each language ``{lang}`` has a top-level subdirectory that contains:
1. ``{lang}/README.rst``: Generated documentation for the language rules
1. ``{lang}/repositories.bzl``: Macro functions that declare repository rule dependencies for that language
2. ``{lang}/{rule}.bzl``: Rule implementations of the form ``{lang}_{kind}_{type}``, where ``kind`` is one of ``proto|grpc`` and
``type`` is one of ``compile|library``
3. ``{lang}/BUILD.bazel``: ``proto_plugin()`` declarations for the available plugins for the language
4. ``example/{lang}/{rule}/``: Generated ``WORKSPACE`` and ``BUILD.bazel`` demonstrating standalone usage of the rules
5. ``{lang}/example/routeguide/``: Example routeguide example implementation, if possible
Rule Generation
***************
To help maintain consistency of the rule implementations and documentation, all of the rule implementations are
generated by the tool ``//tools/rulegen``. Changes in the main ``README.rst`` should be placed in
``tools/rulegen/README.header.rst`` or ``tools/rulegen/README.footer.rst```. Changes to generated rules should be put in the
source files (example: ``tools/rulegen/java.go``).
Developing Custom Plugins
*************************
Generally, follow the pattern seen in the multiple language examples in this
repository. The basic idea is:
1. Load the plugin rule: ``load("@rules_proto_grpc//:defs.bzl", "proto_plugin")``
2. Define the rule, giving it a ``name``, ``options`` (not mandatory), ``tool`` and ``outputs``. ``tool`` is a label that refers
to the binary executable for the plugin itself
3. Choose your output type (pick one!):
- ``outputs``: A list of strings patterns that predicts the pattern of files generated by the plugin. For plugins that
produce one output file per input proto file
- ``out``: The name of a single output file generated by the plugin
- ``output_directory``: Set to true if your plugin generates files in a non-predictable way. e.g. if the output paths
depend on the service names within the files
4. Create a compilation rule and aspect using the following template:
.. code-block:: starlark
load("@rules_proto//proto:defs.bzl", "ProtoInfo")
load(
"@rules_proto_grpc//:defs.bzl",
"ProtoLibraryAspectNodeInfo",
"ProtoPluginInfo",
"proto_compile_aspect_attrs",
"proto_compile_aspect_impl",
"proto_compile_attrs",
"proto_compile_impl",
)
# Create aspect
example_aspect = aspect(
implementation = proto_compile_aspect_impl,
provides = [ProtoLibraryAspectNodeInfo],
attr_aspects = ["deps"],
attrs = dict(
proto_compile_aspect_attrs,
_plugins = attr.label_list(
doc = "List of protoc plugins to apply",
providers = [ProtoPluginInfo],
default = [
Label("//<LABEL OF YOUR PLUGIN>"),
],
),
_prefix = attr.string(
doc = "String used to disambiguate aspects when generating outputs",
default = "example_aspect",
),
),
toolchains = ["@rules_proto_grpc//protobuf:toolchain_type"],
)
# Create compile rule to apply aspect
_rule = rule(
implementation = proto_compile_impl,
attrs = dict(
proto_compile_attrs,
protos = attr.label_list(
mandatory = False, # TODO: set to true in 4.0.0 when deps removed below
providers = [ProtoInfo],
doc = "List of labels that provide the ProtoInfo provider (such as proto_library from rules_proto)",
),
deps = attr.label_list(
mandatory = False,
providers = [ProtoInfo, ProtoLibraryAspectNodeInfo],
aspects = [example_aspect],
doc = "DEPRECATED: Use protos attr",
),
_plugins = attr.label_list(
providers = [ProtoPluginInfo],
default = [
Label("//<LABEL OF YOUR PLUGIN>"),
],
doc = "List of protoc plugins to apply",
),
),
toolchains = [str(Label("//protobuf:toolchain_type"))],
)
# Create macro for converting attrs and passing to compile
def example_compile(**kwargs):
_rule(
verbose_string = "{}".format(kwargs.get("verbose", 0)),
**kwargs
)
License
-------

View File

@ -11,6 +11,8 @@ Protobuf and gRPC rules for `Bazel <https://bazel.build>`_
and `gRPC <https://grpc.io>`_ code and libraries from
`proto_library <https://docs.bazel.build/versions/master/be/protocol-buffer.html#proto_library>`_ targets
`Docs <https://rules_proto_grpc.aliddell.com>`__ | `GitHub <https://github.com/rules-proto-grpc/rules_proto_grpc>`__
.. image:: https://img.shields.io/github/v/tag/rules-proto-grpc/rules_proto_grpc?label=release&sort=semver&color=38a3a5
:alt: Latest Release
:target: https://github.com/rules-proto-grpc/rules_proto_grpc/releases
@ -56,24 +58,24 @@ Contents
- `Overview`_
- `Installation`_
- `Rules`_
- `Android </android>`_
- `Buf </buf>`_
- `C </c>`_
- `C++ </cpp>`_
- `C# </csharp>`_
- `D </d>`_
- `Documentation </doc>`_
- `Go </go>`_
- `grpc-gateway </grpc-gateway>`_
- `Java </java>`_
- `JavaScript </js>`_
- `Objective-C </objc>`_
- `PHP </php>`_
- `Python </python>`_
- `Ruby </ruby>`_
- `Rust </rust>`_
- `Scala </scala>`_
- `Swift </swift>`_
- `Android <android>`_
- `Buf <buf>`_
- `C <c>`_
- `C++ <cpp>`_
- `C# <csharp>`_
- `D <d>`_
- `Documentation <doc>`_
- `Go <go>`_
- `grpc-gateway <grpc-gateway>`_
- `Java <java>`_
- `JavaScript <js>`_
- `Objective-C <objc>`_
- `PHP <php>`_
- `Python <python>`_
- `Ruby <ruby>`_
- `Rust <rust>`_
- `Scala <scala>`_
- `Swift <swift>`_
- `Example Usage`_
- `Developers`_
- `Code Layout`_
@ -115,7 +117,7 @@ Installation
Add ``rules_proto_grpc`` to your ``WORKSPACE`` file and then look at the language specific examples linked below:
.. code-block:: starlark
.. code-block:: python
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

View File

@ -275,8 +275,14 @@ func mustWriteLanguageDefs(dir string, lang *Language) {
func mustWriteLanguageReadme(dir string, lang *Language) {
out := &LineWriter{}
out.w("%s rules", lang.DisplayName)
out.w("%s======", strings.Repeat("=", len(lang.DisplayName)))
out.w(":author: rules_proto_grpc")
out.w(":description: rules_proto_grpc Bazel rules for %s", lang.DisplayName)
out.w(":keywords: Bazel, Protobuf, gRPC, Protocol Buffers, Rules, Build, Starlark, %s", lang.DisplayName)
out.ln()
out.ln()
out.w("%s", lang.DisplayName)
out.w("%s", strings.Repeat("=", len(lang.DisplayName)))
out.ln()
if lang.Notes != nil {
@ -285,7 +291,7 @@ func mustWriteLanguageReadme(dir string, lang *Language) {
}
out.w(".. list-table:: Rules")
out.w(" :widths: 1 1")
out.w(" :widths: 1 2")
out.w(" :header-rows: 1")
out.ln()
out.w(" * - Rule")
@ -312,7 +318,7 @@ func mustWriteLanguageReadme(dir string, lang *Language) {
out.w("*************")
out.ln()
out.w(".. code-block:: starlark")
out.w(".. code-block:: python") // Treat starlark as python, as pygments needs this
out.ln()
out.t(rule.WorkspaceExample, &RuleTemplatingData{lang, rule, commonTemplatingFields}, " ")
out.ln()
@ -321,7 +327,7 @@ func mustWriteLanguageReadme(dir string, lang *Language) {
out.w("***************")
out.ln()
out.w(".. code-block:: starlark")
out.w(".. code-block:: python")
out.ln()
out.t(rule.BuildExample, &RuleTemplatingData{lang, rule, commonTemplatingFields}, " ")
out.ln()
@ -351,6 +357,7 @@ func mustWriteLanguageReadme(dir string, lang *Language) {
out.w("**********")
out.ln()
out.w(".. list-table:: Attributes for %s", rule.Name)
out.w(" :widths: 1 1 1 1 4")
out.w(" :header-rows: 1")
out.ln()
out.w(" * - Name")
@ -362,7 +369,11 @@ func mustWriteLanguageReadme(dir string, lang *Language) {
out.w(" * - ``%s``", attr.Name)
out.w(" - ``%s``", attr.Type)
out.w(" - %t", attr.Mandatory)
if len(attr.Default) > 0 {
out.w(" - ``%s``", attr.Default)
} else {
out.w(" - ")
}
out.w(" - %s", attr.Doc)
}
out.ln()
@ -378,7 +389,7 @@ func mustWriteLanguageReadme(dir string, lang *Language) {
}
}
out.MustWrite(filepath.Join(dir, lang.Dir, "README.rst"))
out.MustWrite(filepath.Join(dir, "docs", "src", lang.Name + ".rst"))
}
func mustWriteReadme(dir, header, footer string, data interface{}, languages []*Language) {
@ -401,9 +412,9 @@ func mustWriteReadme(dir, header, footer string, data interface{}, languages []*
for _, lang := range languages {
for _, rule := range lang.Rules {
dirLink := fmt.Sprintf("`%s </%s>`_", lang.DisplayName, lang.Dir)
ruleLink := fmt.Sprintf("`%s </%s#%s>`_", rule.Name, lang.Dir, rule.Name)
exampleLink := fmt.Sprintf("`example </example/%s/%s>`_", lang.Dir, rule.Name)
dirLink := fmt.Sprintf("`%s <%s>`_", lang.DisplayName, lang.Dir)
ruleLink := fmt.Sprintf("`%s <%s#%s>`_", rule.Name, lang.Dir, rule.Name)
exampleLink := fmt.Sprintf("`example <https://github.com/rules-proto-grpc/rules_proto_grpc/tree/master/example/%s/%s>`__", lang.Dir, rule.Name)
out.w(" * - %s", dirLink)
out.w(" - %s", ruleLink)
out.w(" - %s (%s)", rule.Doc, exampleLink)