وحدات Android Rust

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

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

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

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

يكتب	تعريف	للمزيد من المعلومات
rust_binary	ثنائي الصدأ	صفحة الوحدات الثنائية
rust_library	يُنتج مكتبة Rust ، ويوفر متغيرات rlib و dylib .	rust_library ، صفحة وحدات المكتبة.
rust_ffi	يُنتج مكتبة Rust C قابلة للاستخدام بواسطة وحدات cc، ويوفر متغيرات ثابتة ومشتركة.	rust_ffi ، صفحة وحدات المكتبة
rust_proc_macro	ينتج مكتبة الصدأ proc-macro . (هذه مشابهة للمكونات الإضافية للمترجم.)	rust_proc_macro ، صفحة وحدات المكتبات
rust_test	يُنتج ثنائي اختبار الصدأ الذي يستخدم أداة اختبار الصدأ القياسية.	صفحة وحدات الاختبار
rust_fuzz	ينتج ثنائي Rust Fuzz للاستفادة من libfuzzer .	مثال على وحدة rust_fuzz
rust_protobuf	ينشئ المصدر وينتج مكتبة Rust التي توفر واجهة لبروتوبوف معين.	صفحات وحدات Protobufs ومولدات المصدر
rust_bindgen	يُنشئ المصدر وينتج مكتبة Rust التي تحتوي على روابط Rust لمكتبات C.	وحدات ربط Bindgen وصفحات المولدات المصدرية

خصائص مشتركة هامة

هذه الخصائص شائعة في جميع وحدات Android Rust . يتم إدراج أي خصائص إضافية (فريدة) مرتبطة بوحدات 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.* .

com.srcs

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

عندما يكون ذلك ممكنًا، تجنب هذا الاستخدام لرمز النظام الأساسي؛ راجع مولدات المصدر لمزيد من المعلومات.

crate_name

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

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

الوبر

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

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

clippy_lints

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

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

الإصدار

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

أعلام

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

ld_flags

تحتوي ld-flags على قائمة سلسلة من العلامات لتمريرها إلى الرابط عند تجميع المصدر. يتم تمريرها بواسطة علامة -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 فيما إذا كان سيتم تجريد ملف الإخراج وكيفية تجريده (إن أمكن). إذا لم يتم تعيين هذا، فستقوم وحدات الجهاز الافتراضية بإزالة كل شيء باستثناء معلومات التصحيح المصغرة. لا تقوم الوحدات المضيفة، بشكل افتراضي، بإزالة أي رموز. تتضمن القيم الصالحة none لتعطيل التجريد، all لتجريد كل شيء، بما في ذلك معلومات التصحيح المصغرة. يمكن العثور على قيم إضافية في مرجع وحدات Soong .

host_supported

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

تحديد تبعيات المكتبة

يمكن أن تعتمد وحدات Rust على كل من مكتبات CC و Rust من خلال الخصائص التالية:

اسم الخاصية	وصف
rustlibs	قائمة وحدات rust_library التي تعد أيضًا تبعيات. استخدم هذا كأسلوبك المفضل للإعلان عن التبعيات، لأنه يسمح لنظام البناء بتحديد الارتباط المفضل. (راجع عند الارتباط بمكتبات Rust أدناه)
rlibs	قائمة وحدات rust_library التي يجب ربطها بشكل ثابت كـ rlibs . (استخدم بحذر؛ راجع عند الارتباط بمكتبات Rust أدناه.)
shared_libs	قائمة وحدات cc_library التي يجب ربطها ديناميكيًا كمكتبات مشتركة.
static_libs	قائمة وحدات cc_library التي يجب ربطها بشكل ثابت كمكتبات ثابتة.
whole_static_libs	قائمة وحدات cc_library التي يجب ربطها بشكل ثابت كمكتبات ثابتة وتضمينها بالكامل في المكتبة الناتجة. بالنسبة لمتغيرات rust_ffi_static ، سيتم تضمين whole_static_libraries في أرشيف المكتبة الثابتة الناتج. بالنسبة لمتغيرات rust_library_rlib ، سيتم تجميع مكتبات whole_static_libraries في مكتبة rlib الناتجة.

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

ميزات بناء الدعم غير المدعومة والمحدودة

يقدم Soong's Rust دعمًا محدودًا لصور ولقطات vendor vendor_ramdisk . ومع ذلك، يتم دعم staticlibs و cdylibs و rlibs binaries . بالنسبة لأهداف إنشاء صورة البائع، يتم تعيين الخاصية android_vndk cfg . يمكنك استخدام هذا في التعليمات البرمجية إذا كانت هناك اختلافات بين أهداف النظام والبائعين. لا يتم التقاط rust_proc_macros كجزء من لقطات البائع؛ إذا كانت هذه العناصر تعتمد عليها، فتأكد من التحكم في إصدارها بشكل مناسب.

صور المنتج وVNDK والاسترداد غير مدعومة.

بنيات تزايدية

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

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