puroro, a protocol buffer implementation for Rust

A yet another protocol buffer compiler implementation for Rust language. This project is licensed under Apache 2.0 license.

This is not an officially supported Google product.

See puroro/src/lib.rs for more documents.

important notes

This library is under development and it is very possible to make breaking changes.

Currently this library only supports Rust nightly channel.

How to compile your .pb files to .rs files

First, let's create a crate for your .proto files (and the generated .rs files). Actually it is not required to create a separated crate for the proto files, though I recommend to make it to avoid any unexpected problems.

$ cargo new my-examples --lib
$ cd my-examples

# Create your .proto files under this directory
$ mkdir protos

# Edit your .proto files
$ emacs-vim-nano-or-whatever ./protos/yourproto.proto

As an example, let's make a simple proto file test1.proto:

syntax = "proto3";
package library;
message Book {
    string title = 1;
    uint32 num_pages = 2;
}

Note that the file names does not make any effect in the generated codes. Only the package name (in this case, package library;) makes the effect to the generated code's module name (or file name).

Then edit the Cargo.toml to add the dependency to puroro library crates:

[dependencies]

puroro = "*"



[build-dependencies]

puroro-plugin = "*"

As a last step, create a file build.rs under the crate root directory. Check our sample build.rs and just copy and paste.

Once you have finished these steps, the directory should be like this:

+ my-examples/
    ├ src/
    │   └ (empty)
    ├ protos/
    │   └ test1.proto
    ├ cargo.toml
    ├ build.rs
    ├ (some other generated files)

Then run cargo build command. If it successfully runs, then the generated .rs files will be generated under src/ directory and you can use it from your own crate. Congraturations!

subcrates

• puroro -- The crate that the library user need to import
• codegen -- Generate rust code from the given .proto files info
• plugin -- A protoc compiler plugin
• tests -- Test cases
• tests-pb -- Compiling .pb files used by tests crate
• protobuf -- A git submodule of Google's official protobuf repository
  • When you cloned & checkout the puroro repository, remember to run git submodule init and git submodule update to download this directory.
• puroro-protobuf-compiled -- Compiled .rs files from protobuf crate so that puroro-plugin crate can use it
• puroro-protobuf-compiler -- A crate which only contains build.rs that generates the ...-compiled crate.

TODOs

• proto2
  • Groups, at least correctly ignore it
  • Enums (In proto2 we need to refuse the unknown value)
  • default value (something like optional int32 foo = 1; [default=10])
  • extensions
• proto2 & 3
  • Maps
  • OneOfs
    • Type definitions
    • serialize / deserialize
  • Anys, and other well-known types
  • Enum allow-alias option
  • More more more unit tests
  • More more more more documents
  • Print comments in the generated files
  • Reflections
    • Get message metadata (descriptors)
  • Nightly / stable features
    • Support stable (not using nightly features)
  • Message traits
    • Mutable interface trait
    • (More) Repeated field interface trait
    • Map interface trait
  • Keep unknown fields
  • Deserializer from a slice
  • Serializer performance improvement
  • Custom deserializer (?)
  • Required field checker
  • Other implementations
    • Bumpalo -- Use Bumpalo for Vec and String allocation
    • SliceView -- A viewer over a &[u8] slice, without allocating any extra memories
    • Empty(Unit) -- (), which only returns default values
    • Merged -- (T, U)
    • Either -- ::either::Either<T, U>
    • Option -- Option<T>
  • Support the allocator_api. Waiting for the String support
  • RPCs / services
  • Deserializer vulnerbility: Need to limit the recursion depth
  • Get multiple fields mutable references at once
  • An open struct for each message type so that the user can construct the message instance easily using struct initializer syntax and ..Default::default() syntax.
  • proc_macro to generate the message inline. For testing purpose.