You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+89-22Lines changed: 89 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,38 +6,39 @@
6
6
7
7
<divalign="center">
8
8
9
-
# ` proto-gen`
9
+
# `💠 proto-gen`
10
10
11
-
**Protobuf to `Rust` code generation using tonic-build**
11
+
**[Protobuf](https://protobuf.dev/) to [Rust](https://www.rust-lang.org/) code generation using [tonic-build](https://docs.rs/tonic-build/latest/tonic_build/)**
The repo contains a a cli that uses tonic-build to generate rust-code from protobuf-files.
21
+
The repo contains a cli tool that uses [tonic-build](https://docs.rs/tonic-build/latest/tonic_build/) to generate rust-code from protobuf-files.
21
22
[tonic-build](https://docs.rs/tonic-build/latest/tonic_build/) already does this, the cli is a front-end to
22
23
that with some added code to make sure that the generated files are placed in a valid path, and takes care of the
23
24
module structuring.
24
25
25
26
## Why
26
27
[prost-build](https://docs.rs/prost-build/latest/prost_build/) used to ship with `cmake` which we would like to avoid.
27
28
`cmake` was used to build `protoc` which was then used for the proto-to-rust codegen.
28
-
The final decision from the prost maintainers side is that the user should provide their own protoc and check in the code
29
-
instead of building it in a `build.rs`, to make that process simpler, this cli was created.
29
+
The final decision from the prost maintainers side is that the user should provide their own `protoc` and check in the code
30
+
instead of building it in a `build.rs`, to make that process simpler, therefore this cli was created.
30
31
31
32
## How
32
-
Uses [a local version of protoc on path](https://grpc.io/docs/protoc-installation/) to generate rust code form a
33
-
workspace specification passed to the CLI. The CLI can also be used to validate generated Rust code against source
34
-
protocol files, for example, in CI.
33
+
Uses [a local version of protoc on path](https://grpc.io/docs/protoc-installation/) to generate rust code from a
34
+
workspace specification passed to the CLI. The CLI can also be used to validate the generated Rust code against source
35
+
protobuf files, for example, in CI.
35
36
36
37
## Considerations
37
-
There are quite a few problems with this tool, for now it remains the best alternative for our Protobuf pipeline,
38
+
There are quite a few problems with this tool, for now it remains the best alternative for our protobuf pipeline,
38
39
some things to take into account follows.
39
40
40
-
### Requires manual installations on the user's machine
41
+
### Requires manual installation on the user's machine
41
42
Running this tool requires at minimum `protoc` to be installed on the user's machine,
42
43
many protocol buffers found in the wild have dependencies in the form of other `.proto` files. Which also
43
44
have to be sourced.
@@ -61,38 +62,104 @@ for this tool, although that may be a bit philosophical since the generated code
61
62
### Doc comments are executed
62
63
Tonic converts protobuf comments to doc comments, if these include code examples, cargo will attempt to execute them
63
64
when running `cargo test` (`doc-test` stage).
64
-
This behaviour is different form using `tonic-build`, since those doc-comments are generated where cargo doesn't try
65
+
This behaviour is different from using [tonic-build](https://docs.rs/tonic-build/latest/tonic_build/), since those doc-comments are generated where cargo doesn't try
65
66
to run them.
66
67
Running them is almost always guaranteed to fail in the best case (because they will be non-rust code or not code at all),
67
68
and be a lurking security vulnerability in the worst case where someone have inserted malicious Rust-code in a doc-comment.
68
69
69
70
Ideally it'd be easier to disable running doc-test on a per-module basis. Placing generated protos in a separate lib
70
71
which doesn't run doc-comments is a safer choice, although doc-tests being opt-in would be significantly safer.
To install `proto-gen` from source do the following. This assumed you have installed a recent [rust toolchain](https://www.rust-lang.org/tools/install).
77
+
```
78
+
cargo install --locked proto-gen
79
+
```
80
+
81
+
### Command-line options
82
+
83
+
Usage:
84
+
85
+
```
86
+
proto-gen [OPTIONS] <COMMAND>
78
87
```
88
+
89
+
#### Commands:
90
+
91
+
The top-level commands are:
92
+
93
+
-`validate` Generate new Rust code for proto files, checking current files for differences. Returns error code 1 on any found differences.
94
+
-`generate` Generate new Rust code for proto files, overwriting old files if present.
95
+
-`help` Print this message or the help of the given subcommand(s).
96
+
97
+
`validate` & `generate` share the following sub-options:
98
+
99
+
-`-d`, `--proto-dirs``<PROTO_DIRS>` Directories containing proto files to source (Ex. Dependencies), needs to include any directory containing files to be included in generation.
100
+
-`-f`, `--proto-files``<PROTO_FILES>` The files to be included in generation.
101
+
-`-t`, `--tmp-dir``<TMP_DIR>` Temporary working directory, if left blank, `tempfile` is used to create a temporary directory.
102
+
-`-o`, `--output-dir``<OUTPUT_DIR>` Where to place output files. Will get cleaned up (all contents deleted). A module file will be placed in the parent of this directory.
103
+
-`-h`, `--help` Print help.
104
+
105
+
#### Options:
106
+
The top-level options are:
107
+
108
+
-`-s`, `--build-server` Whether to build server code.
109
+
-`-c`, `--build-client` Whether to build client code.
110
+
-`--generate-transport` Whether to generate the `::connect` and similar functions for tonic.
111
+
-`-d`, `--disable-comments``<DISABLE_COMMENTS>` Disable comments based on proto path. Passing `'.'` disables all comments.
112
+
-`-b`, `--btree-map``<BTREE_MAPS>` Output maps as `BTreeMap` instead of `HashMap`. Passing `'.'` makes all maps `BTreeMap`.
113
+
-`--type-attribute``<TYPE_ATTRIBUTES>` Type attributes to add.
114
+
-`--enum-attribute``<ENUM_ATTRIBUTES>` Enum attributes to add.
115
+
-`--client-attribute``<CLIENT_ATTRIBUTES>` Client mod attributes to add.
116
+
-`--server-attribute``<SERVER_ATTRIBUTES>` Server mod attributes to add.
117
+
-`-f`, `--format` Use `rustfmt` on the code after generation, `rustfmt` needs to be on the path.
118
+
-`-p`, `--prepend-header` Prepend header indicating tool version in generated source files.
119
+
-`--prepend-header-file``<PREPEND_HEADER_FILE>` Prepend header file in generated source files.
120
+
-`--toplevel-attribute``<TOPLEVEL_ATTRIBUTE>` Toplevel mod attribute to add.
121
+
-`-h`, `--help` Print help.
122
+
-`-V`, `--version` Print version.
123
+
124
+
### Examples in this project
79
125
This will generate Rust code from the proto specified in `examples/example-project/proto/my-proto.proto` and place it
This will also generate Rust code (to a temporary directory) and the run a diff against the code contained in `examples/example-project/src/proto_types`.
86
136
If it finds any diffs it will exit with error code 1 and a message.
87
137
88
-
If we want to use includes, the directory to include needs to be specified.
If we want to use includes, the directory to include needs to be specified. Here we're passing `-d` twice, once to include the dependency protos, and one to include the protos we want to generate.
0 commit comments