1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

//! # Protobuf code generator for `protobuf` crate
//!
//! This crate is useful mostly from `build.rs` scripts to generate `.rs` files during the build.
//!
//! # How to generate code
//!
//! There are three main ways to generate `.rs` files from `.proto` files:
//! * using `protoc` command line tool and `protoc-gen-rust` plugin
//! * using this crate `Codegen` with pure rust parser
//! * using this crate `Codegen` with `protoc` parser
//!
//! Which one should you use depends on your needs.
//!
//! If you are using non-cargo build system (like Bazel), you might prefer
//! using `protoc-gen-rust` plugin for `protoc`.
//!
//! If you build with `cargo`, you probably want to use `Codegen` from this crate.
//!
//! # Protoc parser vs pure rust parser
//!
//! There are two protobuf parsers which can be plugged into this crate:
//! * `protoc`-based parser (`protoc` is a command like utility from Google protobuf)
//! * pure rust parser (`protobuf-parse` crate)
//!
//! `protoc`-based parser is expected to parse `.proto` files very correctly:
//! all Google's protobuf implementations rely on it.
//!
//! Where there are no known bugs in `protobuf-parse`, it is not tested very well.
//! Also `protobuf-parse` does not implement certain rarely used features of `.proto` parser,
//! mostly complex message options specified in `.proto` files.
//! I never saw anyone using them, but you have been warned.
//!
//! Note `protoc` command can be obtained from
//! [`protoc-bin-vendored`](https://docs.rs/protoc-bin-vendored) crate.
//!
//! # Version 3
//!
//! Note this is documentation for protobuf-codegen version 3 (which is currently in development).
//!
//! In version 3 this crate encapsulates both `protoc`-based codegen and pure rust codegen.
//!
//! In version 2 `protobuf-codegen` contains `protoc`-based codegen,
//! and `protobuf-codegen-pure` is pure rust codegen.
//!
//! # Example
//!
//! ```no_run
//! // Use this in build.rs
//! protobuf_codegen::Codegen::new()
//!     .includes(&["src/protos"])
//!     // Inputs must reside in some of include paths.
//!     .input("src/protos/apple.proto")
//!     .input("src/protos/banana.proto")
//!     .out_dir("src/protos")
//!     .run_from_script();
//! ```
//!
//! ## How to use `protoc-gen-rust`
//!
//! If you have to.
//!
//! (Note `protoc` can be invoked programmatically with
//! [protoc crate](https://docs.rs/protoc/%3E=3.0.0-alpha))
//!
//! 0) Install protobuf for `protoc` binary.
//!
//! On OS X [Homebrew](https://github.com/Homebrew/brew) can be used:
//!
//! ```sh
//! brew install protobuf
//! ```
//!
//! On Ubuntu, `protobuf-compiler` package can be installed:
//!
//! ```sh
//! apt-get install protobuf-compiler
//! ```
//!
//! Protobuf is needed only for code generation, `rust-protobuf` runtime
//! does not use C++ protobuf library.
//!
//! 1) Install `protoc-gen-rust` program (which is `protoc` plugin)
//!
//! It can be installed either from source or with `cargo install protobuf-codegen` command.
//!
//! 2) Add `protoc-gen-rust` to $PATH
//!
//! If you installed it with cargo, it should be
//!
//! ```sh
//! PATH="$HOME/.cargo/bin:$PATH"
//! ```
//!
//! 3) Generate .rs files:
//!
//! ```sh
//! protoc --rust_out . foo.proto
//! ```
//!
//! This will generate .rs files in current directory.
//!
//! # Customize generate code
//!
//! Sometimes generated code need to be adjusted, e. g. to have custom derives.
//!
//! rust-protobuf provides two options to do that:
//! * generated `.rs` files contain `@@protoc_insertion_point(...)` markers
//!   (similar markers inserts Google's protobuf generator for C++ or Java).
//!   Simple script `sed` one-liners can be used to replace these markers with custom annotations.
//! * `Codegen::customize_callback` can be used to patch generated code
//!   when invoked from `build.rs` script.
//!
//! # Serde
//!
//! rust-protobuf since version 3 no longer directly supports serde.
//!
//! Rust-protobuf 3 fully supports:
//! * runtime reflection
//! * JSON parsing and printing
//!
//! Which covers the most of serde use cases.
//!
//! If you still need serde, generic customization callback (see above) can be used
//! to insert `#[serde(...)]` annotations.
//!
//! [Example project](https://github.com/stepancheg/rust-protobuf/tree/master/protobuf-examples/customize-serde)
//! in the rust-protobuf repository demonstrates how to do it.

#![deny(rustdoc::broken_intra_doc_links)]

mod codegen;
mod compiler_plugin;
mod customize;
mod gen;
pub mod gen_and_write;
pub mod protoc_gen_rust;

pub use codegen::Codegen;
pub use customize::Customize;
pub use customize::CustomizeCallback;
#[doc(hidden)]
pub use gen::paths::proto_name_to_rs;