Protobuf modules

The build system supports generating protobuf interfaces through the rust_protobuf module type.

Basic protobuf code generation is performed with the rust-protobuf crate. To view documentation on this usage, see the GitHub project page with corresponding protobuf examples.

gRPC protobufs are also supported, with generation provided by the grpc-rs crate. To view documentation on this usage, see the documentation on the corresponding gRPC GitHub project page.

Basic rust_protobuf build usage

The following provides an example of defining a protobuf module and using that module as a crate. More details on important properties and how they're used are in the Defining a rust_protobuf section.

If you need to use protobuf generated code through an include!() macro, such as for third-party code, see the Source Generators page for an example. (The example uses a rust_bindgen module, but the means of source inclusion is the same for all source generators.)

Define a rust_protobuf Android.bp module

Assume some proto at src/protos/my.proto relative to your Android.bp; the module is then defined as the following:

rust_protobuf {
    name: "libmy_proto",

    // Crate name that's used to generate the rust_library variants.
    crate_name: "my_proto",

    // Relative paths to the protobuf source files
    protos: ["src/protos/my.proto"],

    // If protobufs define gRPCs, then they should go in grpc_protos
    // instead.
    // grpc_protos: ["src/protos/my.proto"],

    // 'source_stem' controls the output filename.
    // This is the filename that's used in an include! macro.
    source_stem: "my_proto_source",
}

A library that uses this crate is defined by referencing it as if it were any other library dependency:

rust_binary {
    name: "hello_rust_proto",
    srcs: ["src/main.rs"],
    rustlibs: ["libmy_proto"],
}

Crate structure of rust_protobuf modules

Each protobuf file is organized as its own module within the crate, taking the name of the protobuf file. This means all proto base filenames must be unique. For example, take a rust_protobuf defined as follows:

rust_protobuf {
    name: "libfoo",
    crate_name: "foo",
    protos: ["a.proto", "b.proto"],
    grpc_protos: ["c.proto"],
    source_stem: "my_proto_source",
}

The different protos within this crate would be accessed as follows:

// use <crate_name>::<proto_filename>
use foo::a; // protobuf interface defined in a.proto
use foo::b; // protobuf interface defined in b.proto
use foo::c; // protobuf interface defined in c.proto
use foo::c_grpc; // grpc interface defined in c.proto

Notable rust_protobuf properties

The properties defined below are in addition to the Important common properties that apply to all modules. These are either particularly important to Rust protobuf modules, or exhibit unique behavior specific to the rust_protobuf module type.

stem, name, crate_name

rust_protobuf produces library variants, so the same requirements exist for these three properties as they do for the rust_library modules. See the rust_library properties for details.

protos

This is a list of relative paths to the protobuf files to generate the protobuf interface. The base filenames must be unique across protos and grpc_protos.

grpc_protos

The grpc_protos consists of a list of relative paths to the protobuf files that define grpcs to generate the protobuf interface. The base filenames must be unique across protos and grpc_protos.

source_stem

source_stem is the filename for the generated source file that can be included. This is a required field definition, even if you're using the bindings as a crate, since the stem property only controls the output filename for the generated library variants. Unlike other source generators, the filename gets prefixed by mod_, making the final filename mod_<stem>. This prevents name collisions with generated sources from each proto.

Additionally, like the bindgen bindings module, the full set of library properties is also available to control the library compilation, although these rarely need to be defined or changed.