وحدات 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

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

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

srcs

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

تجنَّب هذا الاستخدام لرمز النظام الأساسي قدر الإمكان. لمزيد من المعلومات، يُرجى الاطّلاع على منشئات المصدر .

crate_name

crate_name تضبط بيانات تعريف اسم crate الوصفية من خلال العلامة 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 واسم ملف الإخراج. لمزيد من المعلومات، يُرجى الاطّلاع على قسم " وحدات المكتبات ".

lints

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

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

clippy_lints

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

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

إصدار

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

أعلام

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

ld_flags

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

الميزات

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

cfgs

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

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

• ستتضمّن الوحدات التي تم إنشاؤها كـ dylib علامة android_dylib cfg.

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

strip

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

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، اترُك هذه القيمة غير مضبوطة.