وحدات Rust لنظام التشغيل Android

كقاعدة عامة، تلتزم rust_* تعريفات الوحدات بشكل وثيق باستخدام cc_* وتوقعاته. في ما يلي مثال على تعريف ملف برمجي لملف ثنائي Rust:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

تتناول هذه الصفحة السمات الأكثر شيوعًا لمكوّنات rust_*. للحصول على مزيد من المعلومات عن أنواع وحدات معيّنة وأمثلة على تعريفات الوحدات، اطّلِع على الوحدات الثنائية أو وحدات المكتبة أو وحدات الاختبار.

أنواع الوحدات الأساسية

السمات الشائعة والمهمة

هذه السمات شائعة في جميع وحدات Rust لنظام التشغيل Android. يتم إدراج أيّ مواقع إضافية (فريدة) مرتبطة بوحدات Rust الفردية في صفحة تلك الوحدة.

اسم

name هو اسم وحدتك. ويجب أن يكون هذا العنوان فريدًا في معظم أنواع وحدات Android.bp، تمامًا مثل وحدات Soong الأخرى. يتم استخدام name تلقائيًا كاسمملف المخرج. إذا كان يجب أن يختلف اسم ملف الإخراج عن اسم الوحدة، استخدِم السمة stem لتحديده.

ساق

stem (اختياري) يمنح إمكانية التحكّم المباشر في اسم الملف الناتج (باستثناء امتداد الملف واللاحقات الأخرى). على سبيل المثال، تؤدي rust_library_rlib مكتبة ذات قيمة جذع libfoo إلى إنشاء ملف libfoo.rlib. إذا لم تقدِّم قيمة لسمة stem، سيعتمد اسم ملف الإخراج اسم الوحدة تلقائيًا.

استخدِم الدالة stem عندما يتعذّر عليك ضبط اسم الوحدة على اسم الملف المطلوب للإخراج. على سبيل المثال، تم تسمية rust_library لحزمة log باسم liblog_rust، لأنّه سبق أن تم إنشاء liblog cc_library. يضمن استخدام السمة stem في هذه الحالة تسميةملف المخرج liblog.* بدلاً من liblog_rust.*.

srcs

يحتوي srcs على ملف مصدر واحد يمثّل نقطة الدخول إلى الوحدة (عادةً main.rs أو lib.rs). يعالج rustc عملية حلّ جميع الملفات المصدر الأخرى المطلوبة للترجمة و اكتشافها، ويتم سردها في ملف deps الذي يتم إنشاؤه.

تجنَّب هذا الاستخدام لرمز المنصة كلما أمكن. اطّلِع على أدوات إنشاء الرموز المصدر للحصول على مزيد من المعلومات.

crate_name

يضبط crate_name البيانات الوصفية لاسم الحزمة من خلال rustc --crate_name العلامة. بالنسبة إلى الوحدات التي تُنشئ مكتبات، يجب أن يتطابق هذا مع اسم crate المتوقّع المستخدَم في المصدر. على سبيل المثال، إذا تمت الإشارة إلى الوحدة libfoo_bar في المصدر باسم extern crate foo_bar، يجب أن يكون crate_name: "foo_bar".

هذه السمة شائعة في جميع وحدات rust_*، ولكنها مطلوبة للوحدات التي تُنشئ مكتبات Rust (مثل rust_library rust_ffi وrust_bindgen وrust_protobuf وrust_proc_macro). تفرض هذه الوحدات متطلبات rustc على العلاقة بين crate_name وملف الإخراج. لمزيد من المعلومات، يُرجى الاطّلاع على القسم وحدات المكتبة.

الأخطاء

يتم تشغيل أداة التدقيق rustc linter تلقائيًا لجميع أنواع الوحدات باستثناء أدوات إنشاء المصادر. يتم تحديد بعض مجموعات التدقيق واستخدامها للتحقّق من صحة مصدر الوحدة. في ما يلي القيم المحتمَلة لمجموعات lint هذه:

• default المجموعة التلقائية من أدوات التدقيق، استنادًا إلى موقع الوحدة
• android مجموعة أدوات التدقيق الأكثر صرامة التي تنطبق على جميع رموز نظام Android الأساسية
• vendor مجموعة مُبسّطة من أدوات فحص الأخطاء المطبَّقة على رمز المورّد
• none لتجاهل جميع تحذيرات وخطأ أداة Lint

clippy_lints

يتم أيضًا تشغيل أداة التدقيق clippy تلقائيًا لجميع أنواع الوحدات باستثناء أدوات إنشاء المصادر. تمّ تحديد بضع مجموعات من أدوات التدقيق التي تُستخدَم للتحقّق من صحة مصدر الوحدة. في ما يلي بعض القيمة المحتمَلة:

• default مجموعة تلقائية من أدوات التدقيق حسب موقع الوحدة
• android مجموعة أدوات التدقيق الأكثر صرامة التي تنطبق على جميع رموز نظام Android الأساسية
• vendor مجموعة مُبسّطة من أدوات فحص الأخطاء المطبَّقة على رمز المورّد
• none لتجاهل جميع تحذيرات وخطأ أداة Lint

إصدار

edition يحدِّد إصدار Rust المراد استخدامه ل compiling هذا الرمز. يشبه ذلك إصدارات std لـ C وC++. القيم الصالحة هي 2015 و2018 و2021 (التلقائية).

العلامات

يحتوي flags على قائمة سلاسل من العلامات التي يتم تمريرها إلى rustc أثناء عملية الترجمة.

ld_flags

يحتوي ld-flags على قائمة سلاسل من العلامات لنقلها إلى الرابط عند تجميع الملف المصدر. ويتم تمرير هذه الإعدادات باستخدام العلامة -C linker-args rustc. يتم استخدام clang كواجهة ربط، مع استدعاء lld لإجراء عملية الربط الفعلية.

الميزات

features هي قائمة سلاسل من الميزات التي يجب تفعيلها أثناء عملية الترجمة. ويتم تمرير هذا الرمز إلى rustc بواسطة --cfg 'feature="foo"'. تكون معظم الميزات قابلة للإضافة، لذلك تتألف في كثير من الحالات من مجموعة الميزات الكاملة المطلوبة من جميع الوحدات التابعة. ومع ذلك، في الحالات التي تكون فيها الميزات حصرية لبعضها، حدِّد وحدات إضافية في أي ملفات إنشاء توفّر ميزات متضاربة.

cfgs

يحتوي cfgs على قائمة سلاسل من علامات cfg التي يجب تفعيلها أثناء عملية الترجمة. ويتم نقل هذا الطلب إلى rustc من خلال --cfg foo و--cfg "fizz=buzz".

يضبط نظام الإنشاء تلقائيًا علامات cfg معيّنة في حالات معيّنة، وهي مذكورة أدناه:

• ستحتوي الوحدات التي تم إنشاؤها كملف dylib على مجموعة android_dylib cfg.

• ستتمّ إضافة android_vndk cfg إلى الوحدات التي ستستخدم حزمة VNDK. وهذا مشابه لتعريف __ANDROID_VNDK__ في C++.

شريط

تتحكّم مَعلمة strip في ما إذا كان سيتمّ إزالة البيانات من ملف الإخراج وطريقة إجراء ذلك (إن وُجد). في حال عدم ضبط هذا الخيار، يتم تلقائيًا إزالة كل المحتوى من وحدات الجهاز باستثناء معلومات تصحيح الأخطاء المصغّرة. لا تزيل وحدات المضيف تلقائيًا أي رموز. تشمل القيم الصالحة none لتعطيل عملية الإزالة، وall لإزالة كل شيء، بما في ذلك معلومات تصحيح الأخطاء المصغّرة. يمكن العثور على قيم إضافية في مرجع وحدات Soong.

host_supported

بالنسبة إلى وحدات الأجهزة، تشير المَعلمة host_supported إلى ما إذا كان يجب أن تقدّم الوحدة أيضًا خيار مضيف.

تحديد العناصر التابعة للمكتبة

يمكن أن تعتمد وحدات Rust على كلٍّ من مكتبتَي CC و Rust من خلال السمتَين التاليتَين:

عند الربط بمكتبات Rust، يُنصح باستخدام السمة rustlibs بدلاً من rlibs أو dylibs، ما يُعدّ من بين أفضل الممارسات، ما لم يكن لديك سبب محدّد لإجراء ذلك. ويسمح ذلك لنظام الإنشاء باختيار عملية الربط الصحيحة استنادًا إلى ما تتطلّبه الوحدة الجذر، ويقلّل من احتمال أن تحتوي شجرة التبعيات على كلّ من الإصدارَين rlib و dylib من المكتبة (ما سيؤدي إلى تعذُّر عملية الترجمة).

ميزات الإصدار غير المتوافقة والمتوافقة بشكل محدود

يقدّم Rust من Soong دعمًا محدودًا للصور والنُسخ المصغّرة بتنسيقَي vendor و vendor_ramdisk. ومع ذلك، يمكن استخدام staticlibs وcdylibs rlibs وbinaries. بالنسبة إلى استهدافات إنشاء صور المورّدين، يتم ضبط السمة android_vndk cfg. يمكنك استخدام هذا الإجراء في الرمز البرمجي إذا كانت هناك اختلافات بين استهدافات النظام والمورّدين. rust_proc_macros لا يتم تسجيلها كجزء من لقطات المورّد. وإذا كنت تعتمد على هذه الإصدارات، تأكَّد من التحكّم في الإصدارات بشكلٍ مناسب.

لا تتوفّر صور المنتجات وصور VNDK وصور الاسترداد.

الإصدارات المتزايدة

يمكن للمطوّرين تفعيل عملية الترجمة المتزايدة لمصدر Rust من خلال ضبط متغيّر البيئة SOONG_RUSTC_INCREMENTAL على true.

تحذير: لا يمكن ضمان إنشاء ملفات ثنائية مطابقة لتلك التي يتم إنشاؤها باستخدام برامج Buildbot. قد تختلف عناوين الدوال أو البيانات المضمّنة فيملفّات العناصر. لضمان أنّ العناصر التي تم إنشاؤها متطابقة بنسبة ‎100% مع تلك التي أنشأتها بنية EngProd الأساسية، اترك هذه القيمة غير محدّدة.