وحدات Protobuf

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

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

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

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

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

إذا كنت بحاجة إلى استخدام رمز protobuf تم إنشاؤه من خلال ماكرو include!()، مثل رمز تابع لجهة خارجية، راجِع صفحة Source Generators للاطّلاع على مثال. (يستخدم المثال وحدة 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",
}

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

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

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، تتوفّر أيضًا المجموعة الكاملة من خصائص المكتبة للتحكّم في تجميع المكتبة، على الرغم من أنّ هذه الخصائص نادرًا ما تحتاج إلى تحديدها أو تغييرها.