README

PROST!

prost is a Protocol Buffers
implementation for the Rust Language. prost
generates simple, idiomatic Rust code from proto2 and proto3 files.

Compared to other Protocol Buffers implementations, prost

 Generates simple, idiomatic, and readable Rust types by taking advantage of
  Rust derive attributes.
 Retains comments from .proto files in generated Rust code.
 Allows existing Rust types (not generated from a .proto) to be serialized
  and deserialized by adding attributes.
 Uses the bytes::{Buf, BufMut}
  abstractions for serialization instead of std::io::{Read, Write}.
 Respects the Protobuf package specifier when organizing generated code
  into Rust modules.
 Preserves unknown enum values during deserialization.
 Does not include support for runtime reflection or message descriptors.

 Using prost in a Cargo Project

First, add prost and its public dependencies to your Cargo.toml:

ignore
[dependencies]
prost = "0.14"
 Only necessary if using Protobuf well-known types:
prost-types = "0.14"


The recommended way to add .proto compilation to a Cargo project is to use the
prost-build library. See the [prost-build documentation][prost-build] for
more details and examples.

See the [snazzy repository][snazzy] for a simple start-to-finish example.

[prost-build]: https://docs.rs/prost-build/latest/prost_build/
[snazzy]: https://github.com/danburkert/snazzy

 MSRV

prost will keep a rolling MSRV (minimum supported rust version) policy of at least 6 months. 
When increasing the MSRV, the new Rust version must have been released at least six months ago. 
The current MSRV is 1.85.

 Generated Code

prost generates Rust code from source .proto files using the proto2 or
proto3 syntax. prost's goal is to make the generated code as simple as
possible.

 protoc

With prost-build v0.11 release, protoc will be required to invoke
compile_protos (unless skip_protoc is enabled). Prost will no longer provide
bundled protoc or attempt to compile protoc for users. For install
instructions for protoc, please check out the [protobuf install] instructions.

[protobuf install]: https://github.com/protocolbuffers/protobufprotobuf-compiler-installation


 Packages

Prost can now generate code for .proto files that don't have a package spec.
prost will translate the Protobuf package into
a Rust module. For example, given the package specifier:

[package]: https://protobuf.dev/programming-guides/proto3/packages

protobuf,ignore
package foo.bar;


All Rust types generated from the file will be in the foo::bar module.

 Messages

Given a simple message declaration:

protobuf,ignore
// Sample message.
message Foo {
}


prost will generate the following Rust struct:

rust,ignore
/// Sample message.
[derive(Clone, Debug, PartialEq, Message)]
pub struct Foo {
}


 Fields

Fields in Protobuf messages are translated into Rust as public struct fields of the
corresponding type.

 Scalar Values

Scalar value types are converted as follows:

| Protobuf Type | Rust Type |
| ---