وحدات Protobuf

يتيح نظام الإنشاء إنشاء واجهات protobuf من خلال نوع وحدة rust_protobuf.

يتم إنشاء رمز Protobuf الأساسي باستخدام صندوق rust-protobuf. للاطّلاع على مستندات حول هذا الاستخدام، يُرجى الاطّلاع على صفحة مشروع GitHub مع أمثلة protobuf المناسبة.

تتوفّر أيضًا ملفات protobuf الخاصة بـ gRPC، ويتم إنشاؤها من خلال حزمة grpc-rs. للاطّلاع على مستندات حول هذا الاستخدام، يُرجى الاطّلاع على المستندات في صفحة مشروع gRPC على GitHub.

الاستخدام الأساسي لبناء rust_protobuf

يقدّم ما يلي مثالاً على تحديد وحدة protobuf واستخدام هذه الوحدة كمجموعة. يمكنك الاطّلاع على مزيد من التفاصيل حول السمات المهمة وكيفية استخدامها في القسم تحديد rust_protobuf.

إذا كنت بحاجة إلى استخدام الرمز الذي تم إنشاؤه باستخدام Protobuf من خلال وحدة ماكرو include!()، مثل الرمز البرمجي التابع لجهة خارجية، يمكنك مراجعة صفحة منشئات المصدر للاطّلاع على مثال. (يستخدِم المثال وحدة rust_bindgen، ولكن وسائل تضمين المصدر هي نفسها لجميع أدوات إنشاء المصادر).

تحديد وحدة 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",
}

يمكن الوصول إلى ملفات proto المختلفة ضمن هذا الحِزمة على النحو التالي:

// 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 الأوّلية أو تُظهر سلوكًا فريدًا خاصًا بنوع الوحدة rust_protobuf.

stem وname وcrate_name

تؤدّي السمة rust_protobuf إلى إنشاء صيغ للمكتبة، وبالتالي تنطبق المتطلبات نفسها على هذه السمات الثلاث كما هو الحال في وحدات rust_library. راجِع rust_library للاطّلاع على التفاصيل.

protos

هذه قائمة بالمسارات النسبية لملفات protobuf لإنشاء واجهة protobuf. يجب أن تكون أسماء الملفات الأساسية فريدة في كل من protos وgrpc_protos.

grpc_protos

تتكون grpc_protos من قائمة بالمسارات النسبية لملفات Protobuf التي تحدد grpcs لإنشاء واجهة Protobuf. يجب أن تكون أسماء الملفات الأساسية فريدة في كلّ من protos وgrpc_protos.

source_stem

source_stem هو اسم الملف للملف المصدر الذي تم إنشاؤه الذي يمكن تضمينه. هذا تعريف حقل مطلوب، حتى إذا كنت تستخدم عمليات الربط كصندوق ، لأنّ السمة stem تتحكّم فقط في اسم ملف الإخراج لصيغ المكتبة التي تم إنشاؤها. على عكس منشئي المصادر الآخرين، يُضاف mod_ كبادئة إلى اسم الملف، ما يجعل اسم الملف النهائي هو mod_<stem>. ويمنع ذلك تعارض أسمائها مع المصادر التي تم إنشاؤها من كل ملف proto.

بالإضافة إلى ذلك، تتوفّر أيضًا المجموعة الكاملة من سمات المكتبة للتحكّم في تجميع المكتبة، على الرغم من أنّه نادرًا ما يحتاج المرء إلى تحديدها أو تغييرها، تمامًا مثل وحدة ربطات bindgen.