Skip to content

Update docs for 4.x.x #390

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pcj merged 1 commit into from
Sep 15, 2025
Merged

Update docs for 4.x.x #390

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 19 additions & 30 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# `rules_proto (v3)`
# `rules_proto (v4)`

![build-status](https://github.com/stackb/rules_proto/actions/workflows/ci.yaml/badge.svg)
[![Go Reference](https://pkg.go.dev/badge/github.com/stackb/rules_proto.svg)](https://pkg.go.dev/github.com/stackb/rules_proto)
Expand Down Expand Up @@ -30,38 +30,27 @@ Bazel starlark rules for building protocol buffers +/- gRPC :sparkles:.
## `MODULE.bazel`

```py
bazel_dep(name = "build_stack_rules_proto", version = "3.0.0")
bazel_dep(name = "build_stack_rules_proto", version = "4.x.x")
```

See <https://registry.bazel.build/search?q=rules_proto> for latest version.
> NOTE: `build_stack_rules_proto` is still in the submission process to the bcr.
> Until merged, a git_override or other override is needed to consume this
> repository.

> NOTE: Version 3.x.x no longer supports `WORKSPACE`, please use the latest
> 2.x.x release for workspace compatibility.
See <https://registry.bazel.build/search?q=build_stack_rules_proto> for latest version.

## Docs

| Description | Link |
|-------------------------------------------|----------------------------------------|
| For documentation about the core ruleset | [BUILD_RULES.md](/docs/BUILD_RULES.md) |
| For info about toolchains | [TOOLCHAINS.md](/docs/TOOLCHAINS.md) |
| For help setting up the gazelle extension | [GAZELLE.md](/docs/GAZELLE.md) |
| Writing custom gazelle logic in starlark | [STARLARK.md](/docs/STARLARK.md) |
| For a history of this repository | [HISTORY.md](/docs/HISTORY.md) |
> NOTE: Version 4.x.x no longer supports `WORKSPACE`, please use the latest
> 3.x.x release for workspace compatibility.

## Examples

> Examples are generated from golden tests
## Docs

| Description | Link |
|------------------|-----------------------------------------------|
| commonjs | [commonjs](/docs/commonjs.md) |
| cpp | [cpp](/docs/cpp.md) |
| csharp | [csharp](/docs/csharp.md) |
| go | [go](/docs/go.md) |
| java | [java](/docs/java.md) |
| objc | [objc](/docs/objc.md) |
| ruby | [ruby](/docs/ruby.md) |
| python | [python](/docs/python.md) |
| scala | [scala](/docs/scala.md) |
| proto_repository | [proto_repository](/docs/proto_repository.md) |
| starlark_java | [starlark_java](/docs/starlark_java.md) |
| Description | Link |
|-------------------------------------------|-----------------------------------------|
| Documentation about the core ruleset | [CORE_RULES.md](/docs/CORE_RULES.md) |
| Available Toolchains | [TOOLCHAINS.md](/docs/TOOLCHAINS.md) |
| Guide to setting up the gazelle extension | [GAZELLE.md](/docs/GAZELLE.md) |
| Writing custom gazelle logic | [STARLARK.md](/docs/STARLARK.md) |
| Examples | [example/README.md](/example/README.md) |
| Preconfigured plugins | [PLUGINS.md](/docs/PLUGINS.md) |
| Preconfigured rules | [RULES.md](/docs/RULES.md) |
| A history of this repository | [HISTORY.md](/docs/HISTORY.md) |
0 docs/BUILD_RULES.md → docs/CORE_RULES.md
View file
Open in desktop
File renamed without changes.
116 changes: 9 additions & 107 deletions docs/GAZELLE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,8 +188,7 @@ proto_gazelle(
)
```

- `name`: the rule name
- `gazelle`: a `attr.label` that should point to a `gazelle_binary` rule.
- `gazelle`: an `attr.label` that should point to a `gazelle_binary` rule.
- `cfgs`: an optional `attr.label_list` that references base YAML configuration files.
- `imports`: an optional `attr.label_list` that references CSV files that are
produced by the `proto_repository` rule.
Expand Down Expand Up @@ -256,7 +255,7 @@ proto_go_library(
)
```

### default workspace vendoring strategy: `proto_compiled_sources`
### Default Workspace Vendoring Strategy: `proto_compiled_sources`

For IDE completion and UX, you may decide that it is preferable to vendor the
generated source files into your repo. This is the use case for
Expand Down Expand Up @@ -335,9 +334,9 @@ proto_compile_assets(

> NOTE: the `proto_compile_assets` is not generated by gazelle currently. It
> will require manual rule edits or your own hand-rolled gazelle extension for
> this (pretty easy to write).
> this (not difficult).

### advanced topic: external proto deps with `proto_repository`
### Advanced Topic: external proto deps with `proto_repository`

A common strategy for using protos from other sources is to simply copy them
into your own repo. This works but can be tedious and hard to maintain. The
Expand Down Expand Up @@ -579,14 +578,14 @@ INFO: Running command line: bazel-bin/cmd/bescli/bescli_/bescli

### advanced topic: vendoring external go proto assets with `proto_go_modules`

> This is golang specific
> NOTE: this section is specific to golang only

Given the above, we still have the issue that while `bazel` and `gazelle`
understood how to work with `build_event_service`, the IDE and traditional go
tooling like `go mod tidy` do not. To address this problem, consider
`proto_go_modules`. This rule copies over generated go proto assets to a
`local/` folder (for reasons beyond the scope of this document, `vendor/` does
not work, it has to be a different dir).
not work, it has to be a different directory).

`proto_go_modules` is a separate gazelle extension and a runnable rule. To use
it, first add the extension to your `gazelle_binary`:
Expand Down Expand Up @@ -748,6 +747,7 @@ genproto

```sh
$ cat genproto/github.com/bazelbuild/bazelapis/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream/build_event_stream/go.mod

module github.com/bazelbuild/bazelapis/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream/build_event_stream
go 1.23.1
```
Expand All @@ -758,105 +758,7 @@ The default `go.mod` file has been modified with additional `replace` directives
replace github.com/bazelbuild/bazelapis/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream/build_event_stream => ./genproto/github.com/bazelbuild/bazelapis/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream/build_event_stream
```

## Appendix 1: preconfigured `proto_plugin` rules

```sh
$ bazel query 'kind(proto_plugin,@build_stack_rules_proto//...)' --keep_going
@build_stack_rules_proto//plugin/akka/akka-grpc:protoc-gen-akka-grpc
@build_stack_rules_proto//plugin/bufbuild:connect-es
@build_stack_rules_proto//plugin/bufbuild:es
@build_stack_rules_proto//plugin/builtin:closurejs
@build_stack_rules_proto//plugin/builtin:commonjs
@build_stack_rules_proto//plugin/builtin:cpp
@build_stack_rules_proto//plugin/builtin:csharp
@build_stack_rules_proto//plugin/builtin:java
@build_stack_rules_proto//plugin/builtin:objc
@build_stack_rules_proto//plugin/builtin:php
@build_stack_rules_proto//plugin/builtin:pyi
@build_stack_rules_proto//plugin/builtin:python
@build_stack_rules_proto//plugin/builtin:ruby
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-combo
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogo
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogofast
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogofaster
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogoslick
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogotypes
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gostring
@build_stack_rules_proto//plugin/golang/protobuf:protoc-gen-go
@build_stack_rules_proto//plugin/grpc/grpc:protoc-gen-grpc-cpp
@build_stack_rules_proto//plugin/grpc/grpc:protoc-gen-grpc-python
@build_stack_rules_proto//plugin/grpc/grpc-go:protoc-gen-go-grpc
@build_stack_rules_proto//plugin/grpc/grpc-java:protoc-gen-grpc-java
@build_stack_rules_proto//plugin/grpc/grpc-node:protoc-gen-grpc-node
@build_stack_rules_proto//plugin/grpc/grpc-web:protoc-gen-grpc-web
@build_stack_rules_proto//plugin/scalapb/scalapb:protoc-gen-scala
@build_stack_rules_proto//plugin/scalapb/scalapb:protoc-gen-scala-grpc
@build_stack_rules_proto//plugin/scalapb/zio-grpc:protoc-gen-zio-grpc
@build_stack_rules_proto//plugin/stackb/grpc_js:protoc-gen-grpc-js
@build_stack_rules_proto//plugin/stephenh/ts-proto:protoc-gen-ts-proto
```

## Appendix 2: preconfigured `Plugin` implementations

The plugin name is an opaque string, but by convention they are maven-esqe
artifact identifiers that follow a GitHub org/repo/plugin_name convention.

| Plugin |
|------------------------------------------------------------------------------------------------------------------------|
| [builtin:cpp](pkg/plugin/builtin/cpp_plugin.go) |
| [builtin:csharp](pkg/plugin/builtin/csharp_plugin.go) |
| [builtin:java](pkg/plugin/builtin/java_plugin.go) |
| [builtin:js:closure](pkg/plugin/builtin/js_closure_plugin.go) |
| [builtin:js:common](pkg/plugin/builtin/js_common_plugin.go) |
| [builtin:objc](pkg/plugin/builtin/objc_plugin.go) |
| [builtin:php](pkg/plugin/builtin/php_plugin.go) |
| [builtin:python](pkg/plugin/builtin/python_plugin.go) |
| [builtin:pyi](pkg/plugin/builtin/pyi_plugin.go) |
| [builtin:ruby](pkg/plugin/builtin/ruby_plugin.go) |
| [grpc:grpc:cpp](pkg/plugin/builtin/grpc_grpc_cpp.go) |
| [grpc:grpc:protoc-gen-grpc-python](pkg/plugin/grpc/grpc/protoc-gen-grpc-python.go) |
| [golang:protobuf:protoc-gen-go](pkg/plugin/golang/protobuf/protoc-gen-go.go) |
| [grpc:grpc-go:protoc-gen-go-grpc](pkg/plugin/grpc/grpcgo/protoc-gen-go-grpc.go) |
| [grpc:grpc-java:protoc-gen-grpc-java](pkg/plugin/grpc/grpcjava/protoc-gen-grpc-java.go) |
| [grpc:grpc-node:protoc-gen-grpc-node](pkg/plugin/grpc/grpcnode/protoc-gen-grpc-node.go) |
| [grpc:grpc-web:protoc-gen-grpc-web](pkg/plugin/grpc/grpcweb/protoc-gen-grpc-web.go) |
| [gogo:protobuf:protoc-gen-combo](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
| [gogo:protobuf:protoc-gen-gogo](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
| [gogo:protobuf:protoc-gen-gogofast](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
| [gogo:protobuf:protoc-gen-gogofaster](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
| [gogo:protobuf:protoc-gen-gogoslick](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
| [gogo:protobuf:protoc-gen-gogotypes](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
| [gogo:protobuf:protoc-gen-gostring](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
| [grpc-ecosystem:grpc-gateway:protoc-gen-grpc-gateway](pkg/plugin/grpcecosystem/grpcgateway/protoc-gen-grpc-gateway.go) |
| [scalapb:scalapb:protoc-gen-scala](pkg/plugin/scalapb/scalapb/protoc_gen_scala.go) |
| [stackb:grpc.js:protoc-gen-grpc-js](pkg/plugin/stackb/grpc_js/protoc-gen-grpc-js.go) |
| [stephenh:ts-proto:protoc-gen-ts-proto](pkg/plugin/stephenh/ts-proto/protoc-gen-ts-proto.go) |

## Appendix 3: preconfigured `Rule` implementations

The rule name is an opaque string, but by convention they are maven-esqe
artifact identifiers that follow a GitHub org/repo/rule_name convention.

| Plugin |
|---------------------------------------------------------------------------------------------------|
| [stackb:rules_proto:grpc_cc_library](pkg/rule/rules_cc/grpc_cc_library.go) |
| [stackb:rules_proto:grpc_closure_js_library](pkg/rule/rules_closure/grpc_closure_js_library.go) |
| [stackb:rules_proto:grpc_java_library](pkg/rule/rules_java/grpc_java_library.go) |
| [stackb:rules_proto:grpc_nodejs_library](pkg/rule/rules_nodejs/grpc_nodejs_library.go) |
| [stackb:rules_proto:grpc_web_js_library](pkg/rule/rules_nodejs/grpc_web_js_library.go) |
| [stackb:rules_proto:grpc_py_library](pkg/rule/rules_python/grpc_py_library.go) |
| [stackb:rules_proto:proto_cc_library](pkg/rule/rules_cc/proto_cc_library.go) |
| [stackb:rules_proto:proto_closure_js_library](pkg/rule/rules_closure/proto_closure_js_library.go) |
| [stackb:rules_proto:proto_compile](pkg/protoc/proto_compile.go) |
| [stackb:rules_proto:proto_compiled_sources](pkg/protoc/proto_compiled_sources.go) |
| [stackb:rules_proto:proto_descriptor_set](pkg/protoc/proto_descriptor_set.go) |
| [stackb:rules_proto:proto_go_library](pkg/rule/rules_go/go_library.go) |
| [stackb:rules_proto:proto_java_library](pkg/rule/rules_java/proto_java_library.go) |
| [stackb:rules_proto:proto_nodejs_library](pkg/rule/rules_nodejs/proto_nodejs_library.go) |
| [stackb:rules_proto:proto_py_library](pkg/rule/rules_python/proto_py_library.go) |
| [bazelbuild:rules_scala:scala_proto_library](pkg/rule/rules_scala/scala_proto_library.go) |

## Appendix 4: Registered Flags
## Appendix 1: Registered Flags

- `--proto_configs`: optional config.yaml file(s) that provide preconfiguration
- `--proto_imports_in`: index files to parse and load symbols from
Expand All @@ -870,7 +772,7 @@ artifact identifiers that follow a GitHub org/repo/rule_name convention.
- `--proto_plugin`: register custom starlark plugin of the form
`<file_name>%<plugin_name>`

## Appendix 5: Known Directives
## Appendix 2: Known Directives

### `gazelle:proto_plugin` - Configure Plugin Metadata

Expand Down
13 changes: 10 additions & 3 deletions docs/HISTORY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,13 @@ redesigned around the `proto_library` rule and moved to

## v1

These were pretty good, but open source maintainance was an issue trying to keep up with the matrix of (language * dependencies).
These were pretty good, but open source maintainance was an issue trying to keep
up with the matrix of (language * dependencies).

Partially as a result of that, this ruleset was forked to
<https://github.com/rules-proto-grpc/rules_proto_grpc>. Aspect-based compilation
was featured for quite a while there but later removed. Adam does a great job maintaining that repo. If you're not using gazelle, check it out!
was featured for quite a while there but later removed. Adam does a great job
maintaining that repo. If you're not using gazelle, check it out!

## v2

Expand Down Expand Up @@ -45,4 +47,9 @@ plugins that do things like:

## v3

With v3, WORKSPACE support was dropped in favor of `bzlmod`.
The way gazelle stored resolve data in memory changed in 0.35. Uprading to this
in https://github.com/stackb/rules_proto/pull/357 was a breaking change.

## v4

With v4, `WORKSPACE` support was dropped in favor of `bzlmod`.
Loading
Loading