وحدات المكتبة

هناك نوعان من وحدات مكتبة Rust، أحدهما يُنشئ مكتبات Rust و الآخر يُنشئ مكتبات متوافقة مع C. بالإضافة إلى ذلك، لأغراض نظام الإنشاء، يمكنك اعتبار وحدات الماكرو البروتوكولية في Rust (proc-macros) نوعًا special من المكتبات.

rust_library

تُنشئ وحدة rust_library مكتبات Rust لاستخدامها من قِبل وحدات Rust الأخرى.

بالإضافة إلى أنواع _host، تحتوي مكتبات Rust على أنواع وحدات تتحكّم في عمليات الربط المتاحة.

نوع وحدة مكتبة Rust	التعريف
rust_library	يوفّر كلا خيارَي المكتبة، rlib وdylib. ينصح فريق AOSP باستخدام نوع الوحدات هذا لمكتبات Rust، لأنّه يسمح للوحدات بالعمل بشكل صحيح عند إدراجها كعنصر تابع ضمن السمة rustlibs .
rust_library_rlib	يوفّر هذا النوع فقط الصيغة rlib من مكتبة Rust. لا يمكن ضمان أن تعمل الوحدات التي تقدّم الصيغ rlib فقط مع السمة rustlibs.
rust_library_dylib	يوفّر فقط الصيغة dylib من مكتبة Rust، ولا يمكن ضمان أن تعمل الوحدات التي تقدّم صِيَغ dylib فقط مع السمة rustlibs.

rust_ffi

تُنشئ وحدة rust_ffi مكتبات متوافقة مع C للتوافق مع وحدات CC.

بالإضافة إلى الصيغ _host، تحتوي مكتبات Rust FFI على أنواع وحدات تتحكم في عملية الربط المتاحة، كما هو موضّح في الجدول التالي.

نوع وحدة مكتبة Rust FFI	التعريف
rust_ffi	توفّر كل من الصيغتَين لـ C library: الثابتة والمشترَكة.
rust_ffi_shared	يوفّر هذا الخيار الصيغة C من المكتبة المشتركة فقط.
rust_ffi_static	لا يوفّر سوى نوع مكتبة C الثابتة.

للحصول على مثال أساسي لاستخدام rust_ffi لاستدعاء Rust من C، اطّلِع على صفحة أنماط Rust في Android.

للحصول على معلومات عن الاستخدامات الأكثر تقدمًا، يُرجى الانتقال إلى مستندات Rust الرسمية.

rust_proc_macro

يمكن أن تكون وحدات الماكرو الإجرائية في Rust (proc-macros) مفيدة لتوسيع نطاق المُجمِّع لتنفيذ عمليات تحويل الرموز البرمجية المصدر أو توفير سمات جديدة. يمكن العثور على مزيد من المعلومات حول هذه العناصر في صفحة وحدات الماكرو البرمجية ضمن مستندات Rust الرسمية.

لأغراض نظام الإنشاء، تعمل وحدة rust_proc_macro بطريقة مشابهة لوحدات rust_library. بالنسبة إلى الوحدات التي تعتمد على rust_proc_macros، أضِف اسم الوحدة إلى السمة proc_macros.

بما أنّ proc_macros هي إضافات للمُجمِّع، فإنّها تستهدف بالضرورة المضيف ولا تُنشئ أي رمز يمكن تشغيله على جهاز.

خصائص مكتبة Rust البارزة

إنّ الخصائص المحدّدة في الجدول أدناه هي بالإضافة إلى الخصائص الشائعة والمهمة التي تنطبق على جميع الوحدات. هذه الوحدات إما مهمة بشكل خاص لوحدات مكتبة Rust ، أو تُظهر سلوكًا فريدًا خاصًا بنوع وحدة rust_library.

خصائص مكتبة Rust	التعريف
البادئة / الاسم	يتحكّم السمة stem في اسم ملف مكتبة الإخراج، والذي يتم ضبطه تلقائيًا على name. يفرض مُجمِّع Rust متطلبات معيّنة على أسماء ملفات المكتبة، ونتيجةً لذلك، يفرض نظام الإنشاء هذه المتطلبات لتجنُّب مشاكل الترجمة. يجب أن يمتثل اسم ملف الإخراج لتنسيق lib<crate_name><suffix>. (هناك تبعية هنا للسمة crate_name).
crate_name	هذه السمة مطلوبة للوحدات التي تُنشئ مكتبة. بالإضافة إلى ذلك، لها علاقة باسم ملف الإخراج. (اطّلِع على تعريف stem).
export_include_dirs	بالنسبة إلى وحدات rust_ffi، تحدِّد هذه السمة قائمة بسلسلتَين تمثلان مسارات تضمين نسبية: مسارات تحتوي على رؤوس يمكن لوحدات cc التابعة استخدامها.

ربط rust_library أو rust_ffi

يتمّ تلقائيًا ربط وحدات مكتبة Rust التي تستهدف الأجهزة ديناميكيًا باستخدام libstd. ومع ذلك، يتم ربط وحدات المضيف دائمًا بشكل ثابت بـ libstd.

يعتمد الربط المستخدَم لتبعيات rustlibs على إعدادات الربط المفضّلة للوحدة الأساسية. (على سبيل المثال، سيؤدي استخدام rust_binary مع prefer_rlib: true إلى استخدام صيغ مكتبة Rust التي تربط rustlibs باسم rlibs).

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