1<!-- cargo-sync-readme start -->
2
3# Protobuf code generator
4
5This crate contains protobuf code generator implementation
6and a `protoc-gen-rust` `protoc` plugin.
7
8This crate:
9* provides `protoc-gen-rust` plugin for `protoc` command
10* implement protobuf codegen
11
12This crate is not meant to be used directly, in fact, it does not provide any public API
13(except for `protoc-gen-rust` binary).
14
15Code can be generated with either:
16* `protoc-gen-rust` plugin for `protoc` or
17* [`protoc-rust`](https://docs.rs/protoc) crate
18  (code generator which depends on `protoc` binary for parsing of `.proto` files)
19* [`protobuf-codegen-pure`](https://docs.rs/protobuf-codegen-pure) crate,
20  similar API to `protoc-rust`, but uses pure rust parser of `.proto` files.
21
22# `protoc-gen-rust` plugin for `protoc`
23
24When non-cargo build system is used, consider using standard protobuf code generation pattern:
25`protoc` command does all the work of handling paths and parsing `.proto` files.
26When `protoc` is invoked with `--rust_out=` option, it invokes `protoc-gen-rust` plugin.
27provided by this crate.
28
29When building with cargo, consider using `protoc-rust` or `protobuf-codegen-pure` crates.
30
31## How to use `protoc-gen-rust` if you have to
32
33(Note `protoc` can be invoked programmatically with
34[protoc crate](https://docs.rs/protoc))
35
360) Install protobuf for `protoc` binary.
37
38On OS X [Homebrew](https://github.com/Homebrew/brew) can be used:
39
40```sh
41brew install protobuf
42```
43
44On Ubuntu, `protobuf-compiler` package can be installed:
45
46```sh
47apt-get install protobuf-compiler
48```
49
50Protobuf is needed only for code generation, `rust-protobuf` runtime
51does not use `protobuf` library.
52
531) Install `protoc-gen-rust` program (which is `protoc` plugin)
54
55It can be installed either from source or with `cargo install protobuf` command.
56
572) Add `protoc-gen-rust` to $PATH
58
59If you installed it with cargo, it should be
60
61```sh
62PATH="$HOME/.cargo/bin:$PATH"
63```
64
653) Generate .rs files:
66
67```sh
68protoc --rust_out . foo.proto
69```
70
71This will generate .rs files in current directory.
72
73# Version 2
74
75This is documentation for version 2 of the crate.
76
77[Version 3 of the crate](https://docs.rs/protobuf-codegen/%3E=3.0.0-alpha)
78(currently in development) encapsulates both `protoc` and pure codegens in this crate.
79
80<!-- cargo-sync-readme end -->
81