Moduły Protobuf

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

Podstawowe generowanie kodu protobuf jest wykonywane za pomocą pakietu rust-protobuf. Dokumentację dotyczącą tego zastosowania znajdziesz na stronie projektu w GitHubie, gdzie znajdziesz też odpowiednie przykłady protobuf.

Obsługiwane są też bufory protokołu gRPC, a generowanie zapewnia pakiet grpc-rs. Dokumentację dotyczącą tego zastosowania znajdziesz na stronie odpowiedniego projektu gRPC w GitHubie.

Podstawowe użycie kompilacji rust_protobuf

Poniżej znajdziesz przykład definiowania modułu protobuf i używania go jako pakietu. 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ć wygenerowanego kodu protobuf za pomocą makra include!(), np. w przypadku kodu innej firmy, zapoznaj się z przykładem na stronie Generatory kodu źródłowego. (W przykładzie użyto modułu rust_bindgen, ale sposób włączenia źródła jest taki sam w przypadku wszystkich generatorów źródeł).

Definiowanie modułu rust_protobuf Android.bp

Załóżmy, że plik proto znajduje się w lokalizacji src/protos/my.proto względem pliku Android.bp. 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",
}

Bibliotekę, która korzysta z tego pakietu, definiuje się przez odwołanie się do niego tak, jak do każdej innej zależności biblioteki:

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

Struktura pakietu modułów rust_protobuf

Każdy plik protobuf jest zorganizowany jako osobny moduł w pakiecie, przyjmując nazwę pliku protobuf. Oznacza to, że wszystkie podstawowe nazwy plików proto muszą być unikalne. Weźmy na przykład rust_protobuf zdefiniowany w ten sposób:

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

Dostęp do różnych plików proto w tym pakiecie można uzyskać 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żne właściwości rust_protobuf

Właściwości zdefiniowane poniżej są dodatkowe w stosunku do 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 Rust protobuf lub wykazują unikalne zachowanie charakterystyczne dla typu modułu rust_protobuf.

stem, name, crate_name

rust_protobuf tworzy warianty biblioteki, więc w przypadku tych 3 właściwości obowiązują te same wymagania co w przypadku modułów rust_library. Szczegółowe informacje znajdziesz we właściwościach rust_library.

pliki proto,

Jest to lista ścieżek względnych do plików protobuf, na podstawie których ma zostać wygenerowany interfejs protobuf. Nazwy plików podstawowych muszą być niepowtarzalne w przypadku protos i grpc_protos.

grpc_protos

grpc_protos zawiera listę ścieżek względnych do plików protobuf, które definiują grpcs, aby wygenerować interfejs protobuf. Podstawowe nazwy plików muszą być unikalne w przypadku protos i grpc_protos.

source_stem

source_stem to nazwa pliku wygenerowanego pliku źródłowego, który można uwzględnić. Jest to wymagana definicja pola, nawet jeśli używasz powiązań jako pakietu, ponieważ właściwość stem kontroluje tylko nazwę pliku wyjściowego dla wygenerowanych wariantów biblioteki. W przeciwieństwie do innych generatorów źródeł nazwa pliku jest poprzedzona prefiksem mod_, co sprawia, że ostateczna nazwa pliku to mod_<stem>. Zapobiega to kolizjom nazw ze źródłami wygenerowanymi z każdego pliku proto.

Podobnie jak w przypadku modułu powiązań bindgen, dostępny jest też pełny zestaw właściwości biblioteki, który umożliwia kontrolowanie kompilacji biblioteki, chociaż rzadko trzeba je definiować lub zmieniać.