ماژول های پروتوباف

سیستم ساخت از تولید رابط‌های protobuf از طریق نوع ماژول rust_protobuf پشتیبانی می‌کند.

تولید کد اولیه protobuf با جعبه rust-protobuf انجام می‌شود. برای مشاهده مستندات مربوط به این کاربرد، به صفحه پروژه GitHub با مثال‌های protobuf مربوطه مراجعه کنید.

پروتوباف‌های gRPC نیز پشتیبانی می‌شوند و تولید آنها توسط جعبه grpc-rs انجام می‌شود. برای مشاهده مستندات مربوط به این کاربرد، به مستندات موجود در صفحه پروژه gRPC GitHub مربوطه مراجعه کنید.

کاربرد اولیه‌ی ساخت rust_protobuf

در ادامه مثالی از تعریف یک ماژول protobuf و استفاده از آن ماژول به عنوان جعبه ارائه شده است. جزئیات بیشتر در مورد ویژگی‌های مهم و نحوه استفاده از آنها در بخش تعریف rust_protobuf آمده است.

اگر نیاز دارید از کد تولید شده توسط protobuf از طریق ماکروی include!() استفاده کنید، مثلاً برای کد شخص ثالث، برای مثال به صفحه Source Generators مراجعه کنید. (این مثال از یک ماژول rust_bindgen استفاده می‌کند، اما روش گنجاندن منبع برای همه Source Generatorها یکسان است.)

یک ماژول rust_protobuf Android.bp تعریف کنید

فرض کنید یک پروتو در src/protos/my.proto نسبت به Android.bp شما وجود دارد؛ سپس ماژول به صورت زیر تعریف می‌شود:

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

کتابخانه‌ای که از این جعبه استفاده می‌کند، با ارجاع به آن، مانند هر وابستگی کتابخانه‌ای دیگر، تعریف می‌شود:

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

ساختار جعبه‌ای ماژول‌های rust_protobuf

هر فایل protobuf به عنوان ماژول مخصوص به خود در داخل جعبه سازماندهی می‌شود و نام فایل protobuf را می‌گیرد. این بدان معناست که نام تمام فایل‌های پایه proto باید منحصر به فرد باشد. برای مثال، یک rust_protobuf به صورت زیر تعریف کنید:

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

دسترسی به پروتوهای مختلف درون این جعبه به صورت زیر است:

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

ویژگی‌های قابل توجه rust_protobuf

ویژگی‌های تعریف‌شده در زیر علاوه بر ویژگی‌های مشترک مهمی هستند که برای همه ماژول‌ها اعمال می‌شوند. این ویژگی‌ها یا به‌طور ویژه برای ماژول‌های Rust protobuf مهم هستند، یا رفتار منحصربه‌فردی را مختص به نوع ماژول rust_protobuf نشان می‌دهند.

ساقه، نام، نام جعبه

rust_protobuf انواع کتابخانه تولید می‌کند، بنابراین همان الزاماتی که برای ماژول‌های rust_library وجود دارد، برای این سه ویژگی نیز وجود دارد. برای جزئیات بیشتر به ویژگی‌های rust_library مراجعه کنید.

پروتوس

این فهرستی از مسیرهای نسبی به فایل‌های protobuf برای تولید رابط protobuf است. نام فایل‌های پایه باید در protos و grpc_protos منحصر به فرد باشند.

grpc_protos

grpc_protos شامل فهرستی از مسیرهای نسبی به فایل‌های protobuf است که grpcs برای تولید رابط protobuf تعریف می‌کنند. نام فایل‌های پایه باید در protos و grpc_protos منحصر به فرد باشند.

منبع_stem

source_stem نام فایل منبع تولید شده‌ای است که می‌تواند گنجانده شود. این یک تعریف فیلد الزامی است، حتی اگر از پیوندها به عنوان جعبه استفاده کنید، زیرا ویژگی stem فقط نام فایل خروجی را برای انواع کتابخانه تولید شده کنترل می‌کند. برخلاف سایر مولدهای منبع، نام فایل با mod_ پیشوند می‌شود و نام فایل نهایی mod_<stem> می‌شود. این امر از تداخل نام با منابع تولید شده از هر پروتوتایپ جلوگیری می‌کند.

علاوه بر این، مانند ماژول bindgen bindings، مجموعه کامل ویژگی‌های کتابخانه نیز برای کنترل کامپایل کتابخانه در دسترس است، اگرچه این ویژگی‌ها به ندرت نیاز به تعریف یا تغییر دارند.