وحدات 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 الوحدات الثنائية صفحة
rust_libraryتوفّر مكتبة Rust وتوفّر كل من rlib صيغتان (dylib) rust_library، صفحة "وحدات المكتبة".
rust_ffiلإنشاء مكتبة Rust C قابلة للاستخدام بواسطة الحقل "نسخة إلى" وتوفر صيغًا ثابتة ومشتركة. rust_ffi، صفحة "وحدات المكتبة"
rust_proc_macroلإنشاء مكتبة proc-macro Rust. (تشبه هذه المكوّنات الإضافية لبرامج التجميع). rust_proc_macro، صفحة "وحدات المكتبات"
rust_testتوفر برنامجًا ثنائيًا للاختبار Rust يستخدم دالة حزام اختبار الصدأ القياسي. صفحة الوحدات التجريبية
rust_fuzzإنشاء برنامج ثنائي "زغب" Rust libfuzzer مثال على وحدة rust_fuzz
rust_protobufتنشئ مصدرًا وينتج رمز Rust توفر واجهة لنموذج أوّلي معين. صفحتَا وحدات Protobufs ومنشئات المصدر
rust_bindgenتنشئ مصدرًا وينتج مكتبة Rust التي تحتوي على روابط Rust بمكتبات C. وحدات "الربط" وصفحة منشئات المصدر

السمات المشتركة المهمة

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

اسم

name هو اسم الوحدة. يجب أن تكون هذه الوحدات فريدة، مثلها مثل الوحدات الأخرى في Sumg. في معظم أنواع الوحدات 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. . بالنسبة إلى الوحدات التي تنتج مكتبات، يجب أن تتطابق هذه الوحدة مع اسم القفص المستخدم في المصدر. على سبيل المثال، إذا تمت الإشارة إلى الوحدة 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 بشكل افتراضي لجميع أنواع الوحدات باستثناء أدوات إنشاء المصدر. بعض مجموعات الوبر واستخدامها للتحقق من صحة مصدر الوحدة. القيم المحتملة لهذا الوبر هي على النحو التالي:

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

قصاصة_لينت

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

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

إصدار

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

العلامة

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

علامات_ld_flag

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

الميزات

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

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

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

يضبط نظام التصميم تلقائيًا علامات cfg معيّنة على وجه الخصوص. الموضحة أدناه:

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

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

شريط

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

المضيف_المدعوم

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

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

يمكن أن تعتمد وحدات Rust على كل من الترجمة والشرح مكتبات 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 من المكتبة (مما سيؤدي إلى تعذُّر التجميع).

ميزات إصدار ذات دعم محدود وغير متاحة

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

لا يمكن استخدام صور المنتج وVNDK وصور الاسترداد.

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

يمكن للمطورين تمكين التجميع التزايدي مصدر صدئ عبر ضبط SOONG_RUSTC_INCREMENTAL إلى true.

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