Moduły Protobuf

System kompilacji obsługuje generowanie interfejsów protobuf za pomocą typu modułu rust_protobuf.

Podstawowe generowanie kodu protobuf jest wykonywane za pomocą pakietu rust-protobuf. Dokumentację na temat tego zastosowania znajdziesz na stronie projektu na GitHubie z odpowiednimi przykładami protokołu protobuf.

Obsługiwane są też prototypy gRPC, które są generowane przez crate grpc-rs. Aby wyświetlić dokumentację dotyczącą tego użycia, zapoznaj się z dokumentacją na odpowiedniej stronie projektu gRPC na GitHubie.

Podstawowe użycie rust_protobuf w procesie kompilacji

Poniżej znajdziesz przykład definiowania modułu protobuf i używania go jako paczki. Więcej informacji o ważnych właściwościach i sposobie ich używania znajdziesz w sekcji Definiowanie rust_protobuf.

Jeśli musisz użyć kodu wygenerowanego przez protobuf za pomocą makra include!(), na przykład w przypadku kodu innej firmy, zapoznaj się ze stroną Generatory kodu źródłowego. (Przykład używa modułu rust_bindgen, ale sposób uwzględniania źródła jest taki sam w przypadku wszystkich generatorów źródeł).

Definiowanie modułu Android.bp rust_protobuf

Załóżmy, że w pliku Android.bp znajduje się proto o nazwie src/protos/my.proto. Moduł jest wtedy zdefiniowany w ten sposób:

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",
}

Biblioteka, która korzysta z tego crate, jest zdefiniowana przez odwołanie do niego tak, jakby był on dowolnym innym elementem biblioteki:

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

Struktura pliku crate modułów rust_protobuf

Każdy plik protobuf jest zorganizowany jako własny moduł w ramach pakietu, przy czym przyjmuje nazwę pliku protobuf. Oznacza to, że wszystkie nazwy plików bazy proto muszą być unikalne. Na przykład:rust_protobuf

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

Do różnych prototypów w tym pliku można uzyskać dostęp w ten sposób:

// 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

Ważniejsze właściwości rust_protobuf

Właściwości zdefiniowane poniżej są oprócz ważnych wspólnych właściwości, które mają zastosowanie do wszystkich modułów. Są one szczególnie ważne w przypadku modułów protobuf w Rust lub mają unikalne zachowanie specyficzne dla typu modułu rust_protobuf.

stem, name, crate_name

rust_protobuf generuje warianty biblioteki, więc te 3 usługi mają te same wymagania co moduły rust_library. Więcej informacji znajdziesz w przypadku właściwości rust_library.

protos

Lista ścieżek względnych do plików protobuf służących do wygenerowania interfejsu protobuf. Nazwy plików bazowych muszą być unikalne w przypadku protos i grpc_protos.

grpc_protos

Element grpc_protos zawiera listę ścieżek względnych do plików protobuf, które definiują grpcs do generowania interfejsu protobuf. Nazwy plików bazowych muszą być unikalne w przypadku protos i grpc_protos.

source_stem

source_stem to nazwa wygenerowanego pliku źródłowego, który można uwzględnić. To jest wymagana definicja pola, nawet jeśli używasz tych ograniczeń jako zbioru, ponieważ właściwość stem kontroluje tylko nazwę pliku wyjściowego dla wygenerowanych bibliotek. W odróżnieniu od innych generatorów plików źródłowych nazwa pliku ma prefiks mod_, dzięki czemu ostateczna nazwa pliku to mod_<stem>. Zapobiega to kolizjom nazw z wygenerowanymi źródłami z każdego pliku proto.

Dodatkowo, podobnie jak w przypadku modułu bindgen, dostępny jest też pełny zestaw właściwości biblioteki, które umożliwiają kontrolowanie kompilacji biblioteki, choć rzadko trzeba je definiować lub zmieniać.