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-codegen = "*"
protoc-bin-vendored = "3.0.0"

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
• inline -- Provides a proc macro to directly write proto code in rust code. Currently only used by testing purpose, not published.
• tests -- Test cases

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 original .proto files comments into the generated files
  • Reflections
    • Get message metadata (descriptors)
  • Nightly / stable features
    • Support stable (not using nightly features)
  • Message traits
  • Keep unknown fields
  • Deserializer from a slice
  • Serializer performance improvement
  • Custom deserializer (?)
  • Required field checker
  • Support the allocator_api.
  • RPCs / services
  • 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.