وحدات Protobuf

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

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

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

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

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

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

تحديد وحدة rust_protobuf في ملف Android.bp

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