Protobuf-Module

Das Build-System unterstützt die Generierung von Protobuf-Schnittstellen über den Modultyp rust_protobuf.

Die grundlegende Protobuf-Codegenerierung erfolgt mit der rust-protobuf-Crate. Die Dokumentation zu dieser Verwendung finden Sie auf der GitHub-Projektseite mit entsprechenden Protobuf-Beispielen.

gRPC-Protobufs werden ebenfalls unterstützt. Die Generierung erfolgt über die grpc-rs-Crate. Die Dokumentation zu dieser Verwendung finden Sie auf der entsprechenden gRPC GitHub-Projektseite.

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`rust_protobuf` definieren.

Wenn Sie mit Protobuf generierten Code über ein include!() Makro verwenden müssen, z. B. für Drittanbietercode, finden Sie auf der Seite Quellcodegeneratoren ein Beispiel. Im Beispiel wird ein rust_bindgen-Modul verwendet, aber die Methode zum Einbeziehen von Quellcode ist für alle Quellcodegeneratoren gleich.

Ein Android.bp-Modul für rust_protobuf definieren

Angenommen, Sie haben ein Protobuf unter src/protos/my.proto relativ zu Ihrer Android.bp-Datei. 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 diese Crate verwendet, wird definiert, indem Sie darauf verweisen, als wäre sie 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 in der Crate organisiert und übernimmt den Namen der Protobuf-Datei. Das bedeutet, dass alle Basisdateinamen von Protobufs 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 Protobufs in dieser 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 Attribute gelten zusätzlich zu den wichtigen gemeinsamen Attributen , die für alle Module gelten. Sie 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 erzeugt Bibliotheksvarianten. Daher gelten für diese drei Attribute dieselben Anforderungen wie für die rust_library-Module. Weitere Informationen finden Sie unter den rust_library Attributen.

protos

Dies ist eine Liste relativer Pfade 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 eindeutig für protos und grpc_protos sein.

source_stem

source_stem ist der Dateiname für die generierte Quelldatei, die eingebunden werden kann. Dies ist eine erforderliche Felddefinition, auch wenn Sie die Bindungen als Crate verwenden, da das Attribut stem nur den Ausgabedateinamen für die generierten Bibliotheksvarianten steuert. Im Gegensatz zu anderen Quellcodegeneratoren wird dem Dateinamen das Präfix „mod_“ vorangestellt. Der endgültige Dateiname lautet also mod_<stem>. Dadurch werden Namenskonflikte mit generierten Quellen aus den einzelnen Protobufs vermieden.

Außerdem ist wie beim Bindgen-Bindungsmodul auch die vollständige Gruppe der Bibliotheksattribute verfügbar, um die Bibliothekskompilierung zu steuern. Diese müssen jedoch selten definiert oder geändert werden.