Das Build-System unterstützt das Generieren von Protobuf-Schnittstellen über den Modultyp rust_protobuf.
Die grundlegende protobuf-Codegenerierung erfolgt mit der rust-protobuf-Kiste.
Eine Dokumentation zu dieser Verwendung finden Sie auf der GitHub-Projektseite mit den entsprechenden Protobuf-Beispielen.
gRPC-Protokollpuffer werden ebenfalls unterstützt, wobei die Generierung über den grpc-rs-Speicher bereitgestellt wird.
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 Attributen und deren 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"],
}
Kistenstruktur 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 Proto-Basisdateinamen eindeutig sein müssen. Nehmen wir zum Beispiel ein rust_protobuf, das so definiert ist:
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 dann so 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 Eigenschaften von rust_library.
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 zum Generieren der protobuf-Schnittstelle definieren. 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_<stem> wird. Dadurch werden Namenskonflikte mit generierten Quellen aus jedem Proto vermieden.
Wie beim Bindgen-Bindungsmodul stehen auch hier alle Bibliothekseigenschaften zur Verfügung, um die Bibliothekskompilierung zu steuern. Sie müssen jedoch selten definiert oder geändert werden.