وحدات 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 هو اسم الوحدة. وكما هو الحال مع وحدات Soong الأخرى، يجب أن يكون هذا الاسم فريدًا في معظم Android.bp أنواع الوحدات. يتم تلقائيًا استخدام 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. بالنسبة إلى الوحدات التي تنتج مكتبات، يجب أن يتطابق هذا الاسم تمامًا مع اسم الحزمة المتوقّع المستخدَم في المصدر. على سبيل المثال، إذا تمت الإشارة إلى الوحدة 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 واسم الملف الناتج. لمزيد من المعلومات، راجِع قسم وحدات المكتبة.

أخطاء Lint

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

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

clippy_lints

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

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

إصدار

تحدّد edition إصدار Rust الذي سيتم استخدامه لتجميع هذا الرمز. وهذا مشابه لإصدارات 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 في حالات معيّنة، كما هو موضّح أدناه:

• سيتم ضبط android_dylib cfg للوحدات التي تم إنشاؤها كملف dylib.

• ستحتوي الوحدات التي تستخدم VNDK على مجموعة android_vndk cfg. وهي مشابهة لتعريف __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 وRecovery.

عمليات الإنشاء التزايدية

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

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