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

هناك نوعان من وحدات مكتبة 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

يمكن أن تكون وحدات الماكرو الإجرائية (proc-macros) في Rust مفيدة لتوسيع نطاق المترجم البرمجي بهدف إجراء عمليات تحويل على رمز المصدر أو توفير سمات جديدة. يمكنك الاطّلاع على مزيد من المعلومات حول هذه العناصر في صفحة وحدات الماكرو الإجرائية ضمن مستندات 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).

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