Das Build-System unterstützt die Generierung von Protobuf-Schnittstellen über den Modultyp rust_protobuf.
Die grundlegende Protobuf-Codegenerierung erfolgt mit dem rust-protobuf-Crate.
Die Dokumentation zu dieser Verwendung finden Sie auf der GitHub-Projektseite mit den entsprechenden Protobuf-Beispielen.
gRPC-Protobufs werden ebenfalls unterstützt. Die Generierung erfolgt über das grpc-rs-Crate.
Die Dokumentation zu dieser Verwendung finden Sie auf der entsprechenden 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 über ein include!()-Makro generierten Protobuf-Code verwenden müssen, z. B. für Drittanbietercode, finden Sie ein Beispiel auf der Seite Source Generators. Im Beispiel wird ein rust_bindgen-Modul verwendet, aber die Art der Quellcodeeinbindung ist für alle Quellcodegeneratoren dieselbe.
rust_protobuf-Modul in Android.bp definieren
Angenommen, es gibt ein Proto 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 dieses Crate verwendet, wird definiert, indem darauf verwiesen wird, als wäre es eine 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 ist als eigenes Modul innerhalb des Crate organisiert und trägt den Namen der Protobuf-Datei. Das bedeutet, dass alle Proto-Basisdateinamen eindeutig sein müssen. Nehmen Sie beispielsweise eine rust_protobuf, die 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 Protos in diesem Crate wird 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-Attribute
Die unten definierten Properties gelten zusätzlich zu den wichtigen gemeinsamen Properties, die für alle Module gelten. Diese sind entweder besonders wichtig für Rust-Protobuf-Module oder weisen ein einzigartiges Verhalten auf, das spezifisch für den Modultyp rust_protobuf ist.
stem, name, crate_name
rust_protobuf generiert Bibliotheksvarianten. Daher gelten für diese drei Attribute dieselben Anforderungen wie für die rust_library-Module. Weitere Informationen finden Sie in den Attributen rust_library.
Protos
Dies ist eine Liste mit relativen Pfaden zu den Protobuf-Dateien, aus denen die Protobuf-Schnittstelle generiert werden soll. Die Basisdateinamen müssen für 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 für protos und grpc_protos eindeutig sein.
source_stem
source_stem ist der Dateiname für die generierte Quelldatei, die eingefügt werden kann.
Dies ist eine erforderliche Felddefinition, auch wenn Sie die Bindungen als Crate verwenden, da die stem-Property 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> lautet. Dadurch werden Namenskollisionen mit generierten Quellen aus den einzelnen Protos verhindert.
Wie beim Bindgen-Bindungsmodul ist auch der vollständige Satz von Bibliothekseigenschaften verfügbar, um die Bibliothekskompilierung zu steuern. Diese müssen jedoch selten definiert oder geändert werden.