وحدات Android Rust

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

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

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

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

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

هذه السمات مشترَكة بين جميع وحدات Android Rust. يتم إدراج أيّ مواقع إضافية (فريدة) مرتبطة بوحدات 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. بالنسبة إلى الوحدات التي تنتج المكتبات، يجب أن تتطابق هذه السمة مع اسم القفص المتوقّع المستخدَم في المصدر. على سبيل المثال، إذا تمت الإشارة إلى الوحدة 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 تلقائيًا لجميع أنواع الوحدات باستثناء أدوات إنشاء المصادر. يتم تعريف بعض مجموعات الوبر واستخدامها للتحقق من مصدر الوحدة. في ما يلي القيم المحتمَلة لمجموعات lint هذه:

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

clippy_lints

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

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

إصدار

تحدد edition الإصدار Rust الذي سيتم استخدامه لتجميع هذا الرمز. وهذا يشبه إصدارات std لـ C وC++. والقيمتان الصالحتان هما 2015 و2018 (تلقائي).

العلامات

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

علامات_ld_flag

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

الميزات

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

سلع كهربية أخرى

يحتوي 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.

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