هناك نوعان من وحدات مكتبة Rust، أحدهما ينتج مكتبات Rust والآخر ينتج مكتبات متوافقة مع C. بالإضافة إلى ذلك، يمكنك اعتبار وحدات الماكرو الإجرائية في Rust (proc-macros) نوعًا خاصًا من المكتبات لأغراض نظام الإنشاء.
rust_library
ينتج الوحدة rust_library مكتبات Rust لاستخدامها من قِبل وحدات Rust الأخرى.
بالإضافة إلى صيغ _host، تحتوي مكتبات Rust على أنواع وحدات تحكّم في الربط المتاح.
| Rust Library Module Type | التعريف |
|---|---|
| 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 Library Module Type | التعريف |
|---|---|
| rust_ffi | توفّر كلا نوعَي مكتبة C: الثابتة والمشترَكة. |
| rust_ffi_shared | توفّر هذه السمة صيغة مكتبة C المشتركة فقط. |
| rust_ffi_static | توفّر هذه السمة نوع مكتبة C الثابتة فقط. |
للاطّلاع على مثال أساسي لاستخدام rust_ffi من أجل استدعاء Rust من C، راجِع صفحة
نماذج Android Rust.
للحصول على معلومات حول الاستخدام الأكثر تقدّمًا، يُرجى الانتقال إلى مستندات 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 متطلبات معيّنة على أسماء ملفات المكتبات، ونتيجةً لذلك، يفرض نظام الإنشاء هذه المتطلبات لتجنُّب مشاكل الترجمة البرمجية.
يجب أن يتوافق اسم ملف الإخراج مع التنسيق |
| 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).
للسماح بإنتاج وحدات تابعة للجذر لا تعتمد على أي مكتبات ديناميكية بلغة Rust (مثل الملفات التنفيذية الثابتة)، يوفّر rlibs كلا النوعين الديناميكي والثابت من خيارات الربط libstd. يتم ربط الصيغة الصحيحة تلقائيًا بواسطة Soong.