Skip to content

Commit eaffb93

Browse files
pcjpcj
authored
Update docs for 4.x.x (#390)
1 parent d555e49 commit eaffb93

File tree

9 files changed

+180
-348
lines changed

9 files changed

+180
-348
lines changed

‎README.md‎

Lines changed: 19 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# `rules_proto (v3)`
1+
# `rules_proto (v4)`
22

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

3232
```py
33-
bazel_dep(name = "build_stack_rules_proto", version = "3.0.0")
33+
bazel_dep(name = "build_stack_rules_proto", version = "4.x.x")
3434
```
3535

36-
See <https://registry.bazel.build/search?q=rules_proto> for latest version.
36+
> NOTE: `build_stack_rules_proto` is still in the submission process to the bcr.
37+
> Until merged, a git_override or other override is needed to consume this
38+
> repository.
3739
38-
> NOTE: Version 3.x.x no longer supports `WORKSPACE`, please use the latest
39-
> 2.x.x release for workspace compatibility.
40+
See <https://registry.bazel.build/search?q=build_stack_rules_proto> for latest version.
4041

41-
## Docs
42-
43-
| Description | Link |
44-
|-------------------------------------------|----------------------------------------|
45-
| For documentation about the core ruleset | [BUILD_RULES.md](/docs/BUILD_RULES.md) |
46-
| For info about toolchains | [TOOLCHAINS.md](/docs/TOOLCHAINS.md) |
47-
| For help setting up the gazelle extension | [GAZELLE.md](/docs/GAZELLE.md) |
48-
| Writing custom gazelle logic in starlark | [STARLARK.md](/docs/STARLARK.md) |
49-
| For a history of this repository | [HISTORY.md](/docs/HISTORY.md) |
42+
> NOTE: Version 4.x.x no longer supports `WORKSPACE`, please use the latest
43+
> 3.x.x release for workspace compatibility.
5044
51-
## Examples
52-
53-
> Examples are generated from golden tests
45+
## Docs
5446

55-
| Description | Link |
56-
|------------------|-----------------------------------------------|
57-
| commonjs | [commonjs](/docs/commonjs.md) |
58-
| cpp | [cpp](/docs/cpp.md) |
59-
| csharp | [csharp](/docs/csharp.md) |
60-
| go | [go](/docs/go.md) |
61-
| java | [java](/docs/java.md) |
62-
| objc | [objc](/docs/objc.md) |
63-
| ruby | [ruby](/docs/ruby.md) |
64-
| python | [python](/docs/python.md) |
65-
| scala | [scala](/docs/scala.md) |
66-
| proto_repository | [proto_repository](/docs/proto_repository.md) |
67-
| starlark_java | [starlark_java](/docs/starlark_java.md) |
47+
| Description | Link |
48+
|-------------------------------------------|-----------------------------------------|
49+
| Documentation about the core ruleset | [CORE_RULES.md](/docs/CORE_RULES.md) |
50+
| Available Toolchains | [TOOLCHAINS.md](/docs/TOOLCHAINS.md) |
51+
| Guide to setting up the gazelle extension | [GAZELLE.md](/docs/GAZELLE.md) |
52+
| Writing custom gazelle logic | [STARLARK.md](/docs/STARLARK.md) |
53+
| Examples | [example/README.md](/example/README.md) |
54+
| Preconfigured plugins | [PLUGINS.md](/docs/PLUGINS.md) |
55+
| Preconfigured rules | [RULES.md](/docs/RULES.md) |
56+
| A history of this repository | [HISTORY.md](/docs/HISTORY.md) |

docs/BUILD_RULES.md renamed to docs/CORE_RULES.md

File renamed without changes.

‎docs/GAZELLE.md‎

Lines changed: 9 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -188,8 +188,7 @@ proto_gazelle(
188188
)
189189
```
190190

191-
- `name`: the rule name
192-
- `gazelle`: a `attr.label` that should point to a `gazelle_binary` rule.
191+
- `gazelle`: an `attr.label` that should point to a `gazelle_binary` rule.
193192
- `cfgs`: an optional `attr.label_list` that references base YAML configuration files.
194193
- `imports`: an optional `attr.label_list` that references CSV files that are
195194
produced by the `proto_repository` rule.
@@ -256,7 +255,7 @@ proto_go_library(
256255
)
257256
```
258257

259-
### default workspace vendoring strategy: `proto_compiled_sources`
258+
### Default Workspace Vendoring Strategy: `proto_compiled_sources`
260259

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

336335
> NOTE: the `proto_compile_assets` is not generated by gazelle currently. It
337336
> will require manual rule edits or your own hand-rolled gazelle extension for
338-
> this (pretty easy to write).
337+
> this (not difficult).
339338
340-
### advanced topic: external proto deps with `proto_repository`
339+
### Advanced Topic: external proto deps with `proto_repository`
341340

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

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

582-
> This is golang specific
581+
> NOTE: this section is specific to golang only
583582
584583
Given the above, we still have the issue that while `bazel` and `gazelle`
585584
understood how to work with `build_event_service`, the IDE and traditional go
586585
tooling like `go mod tidy` do not. To address this problem, consider
587586
`proto_go_modules`. This rule copies over generated go proto assets to a
588587
`local/` folder (for reasons beyond the scope of this document, `vendor/` does
589-
not work, it has to be a different dir).
588+
not work, it has to be a different directory).
590589

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

749748
```sh
750749
$ cat genproto/github.com/bazelbuild/bazelapis/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream/build_event_stream/go.mod
750+
751751
module github.com/bazelbuild/bazelapis/src/main/java/com/google/devtools/build/lib/buildeventstream/proto/build_event_stream/build_event_stream
752752
go 1.23.1
753753
```
@@ -758,105 +758,7 @@ The default `go.mod` file has been modified with additional `replace` directives
758758
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
759759
```
760760

761-
## Appendix 1: preconfigured `proto_plugin` rules
762-
763-
```sh
764-
$ bazel query 'kind(proto_plugin,@build_stack_rules_proto//...)' --keep_going
765-
@build_stack_rules_proto//plugin/akka/akka-grpc:protoc-gen-akka-grpc
766-
@build_stack_rules_proto//plugin/bufbuild:connect-es
767-
@build_stack_rules_proto//plugin/bufbuild:es
768-
@build_stack_rules_proto//plugin/builtin:closurejs
769-
@build_stack_rules_proto//plugin/builtin:commonjs
770-
@build_stack_rules_proto//plugin/builtin:cpp
771-
@build_stack_rules_proto//plugin/builtin:csharp
772-
@build_stack_rules_proto//plugin/builtin:java
773-
@build_stack_rules_proto//plugin/builtin:objc
774-
@build_stack_rules_proto//plugin/builtin:php
775-
@build_stack_rules_proto//plugin/builtin:pyi
776-
@build_stack_rules_proto//plugin/builtin:python
777-
@build_stack_rules_proto//plugin/builtin:ruby
778-
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-combo
779-
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogo
780-
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogofast
781-
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogofaster
782-
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogoslick
783-
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gogotypes
784-
@build_stack_rules_proto//plugin/gogo/protobuf:protoc-gen-gostring
785-
@build_stack_rules_proto//plugin/golang/protobuf:protoc-gen-go
786-
@build_stack_rules_proto//plugin/grpc/grpc:protoc-gen-grpc-cpp
787-
@build_stack_rules_proto//plugin/grpc/grpc:protoc-gen-grpc-python
788-
@build_stack_rules_proto//plugin/grpc/grpc-go:protoc-gen-go-grpc
789-
@build_stack_rules_proto//plugin/grpc/grpc-java:protoc-gen-grpc-java
790-
@build_stack_rules_proto//plugin/grpc/grpc-node:protoc-gen-grpc-node
791-
@build_stack_rules_proto//plugin/grpc/grpc-web:protoc-gen-grpc-web
792-
@build_stack_rules_proto//plugin/scalapb/scalapb:protoc-gen-scala
793-
@build_stack_rules_proto//plugin/scalapb/scalapb:protoc-gen-scala-grpc
794-
@build_stack_rules_proto//plugin/scalapb/zio-grpc:protoc-gen-zio-grpc
795-
@build_stack_rules_proto//plugin/stackb/grpc_js:protoc-gen-grpc-js
796-
@build_stack_rules_proto//plugin/stephenh/ts-proto:protoc-gen-ts-proto
797-
```
798-
799-
## Appendix 2: preconfigured `Plugin` implementations
800-
801-
The plugin name is an opaque string, but by convention they are maven-esqe
802-
artifact identifiers that follow a GitHub org/repo/plugin_name convention.
803-
804-
| Plugin |
805-
|------------------------------------------------------------------------------------------------------------------------|
806-
| [builtin:cpp](pkg/plugin/builtin/cpp_plugin.go) |
807-
| [builtin:csharp](pkg/plugin/builtin/csharp_plugin.go) |
808-
| [builtin:java](pkg/plugin/builtin/java_plugin.go) |
809-
| [builtin:js:closure](pkg/plugin/builtin/js_closure_plugin.go) |
810-
| [builtin:js:common](pkg/plugin/builtin/js_common_plugin.go) |
811-
| [builtin:objc](pkg/plugin/builtin/objc_plugin.go) |
812-
| [builtin:php](pkg/plugin/builtin/php_plugin.go) |
813-
| [builtin:python](pkg/plugin/builtin/python_plugin.go) |
814-
| [builtin:pyi](pkg/plugin/builtin/pyi_plugin.go) |
815-
| [builtin:ruby](pkg/plugin/builtin/ruby_plugin.go) |
816-
| [grpc:grpc:cpp](pkg/plugin/builtin/grpc_grpc_cpp.go) |
817-
| [grpc:grpc:protoc-gen-grpc-python](pkg/plugin/grpc/grpc/protoc-gen-grpc-python.go) |
818-
| [golang:protobuf:protoc-gen-go](pkg/plugin/golang/protobuf/protoc-gen-go.go) |
819-
| [grpc:grpc-go:protoc-gen-go-grpc](pkg/plugin/grpc/grpcgo/protoc-gen-go-grpc.go) |
820-
| [grpc:grpc-java:protoc-gen-grpc-java](pkg/plugin/grpc/grpcjava/protoc-gen-grpc-java.go) |
821-
| [grpc:grpc-node:protoc-gen-grpc-node](pkg/plugin/grpc/grpcnode/protoc-gen-grpc-node.go) |
822-
| [grpc:grpc-web:protoc-gen-grpc-web](pkg/plugin/grpc/grpcweb/protoc-gen-grpc-web.go) |
823-
| [gogo:protobuf:protoc-gen-combo](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
824-
| [gogo:protobuf:protoc-gen-gogo](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
825-
| [gogo:protobuf:protoc-gen-gogofast](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
826-
| [gogo:protobuf:protoc-gen-gogofaster](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
827-
| [gogo:protobuf:protoc-gen-gogoslick](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
828-
| [gogo:protobuf:protoc-gen-gogotypes](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
829-
| [gogo:protobuf:protoc-gen-gostring](pkg/plugin/gogo/protobuf/protoc-gen-gogo.go) |
830-
| [grpc-ecosystem:grpc-gateway:protoc-gen-grpc-gateway](pkg/plugin/grpcecosystem/grpcgateway/protoc-gen-grpc-gateway.go) |
831-
| [scalapb:scalapb:protoc-gen-scala](pkg/plugin/scalapb/scalapb/protoc_gen_scala.go) |
832-
| [stackb:grpc.js:protoc-gen-grpc-js](pkg/plugin/stackb/grpc_js/protoc-gen-grpc-js.go) |
833-
| [stephenh:ts-proto:protoc-gen-ts-proto](pkg/plugin/stephenh/ts-proto/protoc-gen-ts-proto.go) |
834-
835-
## Appendix 3: preconfigured `Rule` implementations
836-
837-
The rule name is an opaque string, but by convention they are maven-esqe
838-
artifact identifiers that follow a GitHub org/repo/rule_name convention.
839-
840-
| Plugin |
841-
|---------------------------------------------------------------------------------------------------|
842-
| [stackb:rules_proto:grpc_cc_library](pkg/rule/rules_cc/grpc_cc_library.go) |
843-
| [stackb:rules_proto:grpc_closure_js_library](pkg/rule/rules_closure/grpc_closure_js_library.go) |
844-
| [stackb:rules_proto:grpc_java_library](pkg/rule/rules_java/grpc_java_library.go) |
845-
| [stackb:rules_proto:grpc_nodejs_library](pkg/rule/rules_nodejs/grpc_nodejs_library.go) |
846-
| [stackb:rules_proto:grpc_web_js_library](pkg/rule/rules_nodejs/grpc_web_js_library.go) |
847-
| [stackb:rules_proto:grpc_py_library](pkg/rule/rules_python/grpc_py_library.go) |
848-
| [stackb:rules_proto:proto_cc_library](pkg/rule/rules_cc/proto_cc_library.go) |
849-
| [stackb:rules_proto:proto_closure_js_library](pkg/rule/rules_closure/proto_closure_js_library.go) |
850-
| [stackb:rules_proto:proto_compile](pkg/protoc/proto_compile.go) |
851-
| [stackb:rules_proto:proto_compiled_sources](pkg/protoc/proto_compiled_sources.go) |
852-
| [stackb:rules_proto:proto_descriptor_set](pkg/protoc/proto_descriptor_set.go) |
853-
| [stackb:rules_proto:proto_go_library](pkg/rule/rules_go/go_library.go) |
854-
| [stackb:rules_proto:proto_java_library](pkg/rule/rules_java/proto_java_library.go) |
855-
| [stackb:rules_proto:proto_nodejs_library](pkg/rule/rules_nodejs/proto_nodejs_library.go) |
856-
| [stackb:rules_proto:proto_py_library](pkg/rule/rules_python/proto_py_library.go) |
857-
| [bazelbuild:rules_scala:scala_proto_library](pkg/rule/rules_scala/scala_proto_library.go) |
858-
859-
## Appendix 4: Registered Flags
761+
## Appendix 1: Registered Flags
860762

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

873-
## Appendix 5: Known Directives
775+
## Appendix 2: Known Directives
874776

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

‎docs/HISTORY.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,13 @@ redesigned around the `proto_library` rule and moved to
99

1010
## v1
1111

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

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

1820
## v2
1921

@@ -45,4 +47,9 @@ plugins that do things like:
4547

4648
## v3
4749

48-
With v3, WORKSPACE support was dropped in favor of `bzlmod`.
50+
The way gazelle stored resolve data in memory changed in 0.35. Uprading to this
51+
in https://github.com/stackb/rules_proto/pull/357 was a breaking change.
52+
53+
## v4
54+
55+
With v4, `WORKSPACE` support was dropped in favor of `bzlmod`.

0 commit comments

Comments
 (0)