Das Build-System unterstützt das Generieren von Protobuf-Schnittstellen über den Modultyp rust_protobuf.
Die grundlegende protobuf-Codegenerierung erfolgt mit dem rust-protobuf-Crate.
Eine entsprechende Dokumentation finden Sie auf der GitHub-Projektseite mit den entsprechenden Protobuf-Beispielen.
gRPC-Protobufs werden ebenfalls unterstützt. Die Generierung erfolgt über den grpc-rs-Crate.
Eine entsprechende Dokumentation finden Sie auf der GitHub-Projektseite für gRPC.
Grundlegende Verwendung von rust_protobuf-Builds
Im Folgenden finden Sie ein Beispiel für die Definition eines Protobuf-Moduls und die Verwendung dieses Moduls als Crate. Weitere Informationen zu wichtigen Properties und ihrer Verwendung finden Sie im Abschnitt rust_protobuf definieren.
Wenn Sie protobuf-generierten Code über ein include!()-Makro verwenden müssen, z. B. für Code von Drittanbietern, finden Sie auf der Seite Quellcodegeneratoren ein Beispiel. Im Beispiel wird ein rust_bindgen-Modul verwendet, die Einbindung von Quellen ist jedoch für alle Quellgeneratoren gleich.
rust_protobuf Android.bp-Modul definieren
Angenommen, ein Prototyp befindet sich unter src/protos/my.proto relativ zu Ihrem Android.bp. Das Modul wird dann so definiert:
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",
}
Eine Bibliothek, die diesen Crate verwendet, wird definiert, indem auf ihn verwiesen wird, als wäre er eine beliebige andere Bibliotheksabhängigkeit:
rust_binary {
name: "hello_rust_proto",
srcs: ["src/main.rs"],
rustlibs: ["libmy_proto"],
}
Crate-Struktur von rust_protobuf-Modulen
Jede protobuf-Datei wird als eigenes Modul innerhalb des Crates organisiert und nimmt den Namen der protobuf-Datei an. Das bedeutet, dass alle Basisdateinamen für Proto eindeutig sein müssen. Angenommen, rust_protobuf ist so definiert:
rust_protobuf {
name: "libfoo",
crate_name: "foo",
protos: ["a.proto", "b.proto"],
grpc_protos: ["c.proto"],
source_stem: "my_proto_source",
}
Auf die verschiedenen Prototypdateien in diesem Crate wird folgendermaßen zugegriffen:
// 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
Wichtige rust_protobuf-Properties
Die unten definierten Properties ergänzen die wichtigen allgemeinen Properties, die für alle Module gelten. Diese sind entweder besonders wichtig für Rust-Protobuf-Module oder weisen ein einzigartiges Verhalten auf, das für den rust_protobuf-Modultyp spezifisch ist.
stem, name, crate_name
rust_protobuf generiert Bibliotheksvarianten. Daher gelten für diese drei Properties dieselben Anforderungen wie für die rust_library-Module. Weitere Informationen finden Sie in den rust_library-Properties.
protos
Dies ist eine Liste der relativen Pfade zu den Protobuf-Dateien, um die Protobuf-Schnittstelle zu generieren. Die Basisdateinamen müssen in protos und grpc_protos eindeutig sein.
grpc_protos
grpc_protos besteht aus einer Liste relativer Pfade zu den Protobuf-Dateien, die grpcs definieren, um die Protobuf-Schnittstelle zu generieren. Die Basisdateinamen müssen in protos und grpc_protos eindeutig sein.
source_stem
source_stem ist der Dateiname der generierten Quelldatei, die eingefügt werden kann.
Diese Felddefinition ist erforderlich, auch wenn Sie die Bindungen als Crate verwenden, da die Property stem nur den Ausgabedateinamen für die generierten Bibliotheksvarianten steuert. Im Gegensatz zu anderen Quellgeneratoren wird dem Dateinamen das Präfix „mod_“ vorangestellt, sodass der endgültige Dateiname mod_<Stamm> lautet. Dadurch werden Namenskollisionen mit generierten Quellen aus den einzelnen Proto-Dateien vermieden.
Wie beim Bindgen-Bindungsmodul stehen auch hier alle Bibliothekseigenschaften zur Verfügung, um die Bibliothekskompilierung zu steuern. Diese müssen jedoch selten definiert oder geändert werden.