أدوات إنشاء المصادر

bookmark_border تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تقدّم هذه الصفحة نظرة عامة على مدى توافق المصدر الذي تم إنشاؤه و كيفية استخدامه في نظام الإنشاء.

توفّر جميع أدوات إنشاء المصادر وظائف مماثلة لنظام الإنشاء. إنّ حالات الاستخدام الثلاث لإنشاء المصادر المتوافقة مع نظام الإنشاء هي إنشاء ربطات C باستخدام bindgen وواجهات AIDL وواجهات protobuf.

الصناديق من مصدر تم إنشاؤه

يمكن استخدام كل وحدة Rust التي تنشئ رمز مصدر كحزمة، تمامًا كما هو الحال إذا تم تحديدها على أنّها rust_library. (يعني ذلك أنّه يمكن تعريفه على أنّه ملف مستند في السمات rustlibs وrlibs وdylibs). أفضل نمط استخدام لرمز النظام الأساسي هو استخدام المصدر الذي تم إنشاؤه كحزمة. على الرغم من أنّ الماكرو include! متوافق مع المصدر الذي تم إنشاؤه، إلا أنّ الغرض الأساسي منه هو إتاحة استخدام الرمز البرمجي التابع لجهة خارجية والمضمّن في external/.

في بعض الحالات، قد يستمر رمز النظام الأساسي في استخدام المصدر الذي تم إنشاؤه من خلال الماكرو include!()، مثل استخدام وحدة genrule لإنشاء مصدر بطريقة فريدة.

استخدِم include!() لتضمين المصدر الذي تم إنشاؤه.

يتناول القسم "أمثلة" في كل صفحة وحدة (معنيّة) استخدام المصدر الذي تم إنشاؤه كحزمة. يوضّح هذا القسم كيفية الإشارة إلى المصدر الذي تم إنشاؤه من خلال وحدة الماكرو include!(). تجدر الإشارة إلى أنّ هذه العملية متشابهة لجميع أدوات توليد المصادر.

المتطلبات الأساسية

يستند هذا المثال إلى الافتراض بأنّك حدّدت rust_bindgen وحدة (libbuzz_bindgen) ويمكنك المتابعة إلى خطوات تضمين المصدر الذي تم إنشاؤه لاستخدام الماكروinclude!(). إذا لم يسبق لك ذلك، يُرجى الانتقال إلى مقالة تحديد وحدة rust bindgen، إنشاء libbuzz_bindgen، ثم الرجوع إلى هنا.

يُرجى العلم أنّ أجزاء ملف الإنشاء من هذا الإجراء تنطبق على جميع أدوات إنشاء المصادر.

خطوات تضمين المصدر الذي تم إنشاؤه

أنشئ external/rust/hello_bindgen/Android.bp يتضمّن المحتوى التالي:

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

أنشئ external/rust/hello_bindgen/src/bindings.rs يتضمّن المحتوى التالي:

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

أنشئ external/rust/hello_bindgen/src/lib.rs يتضمّن المحتوى التالي:

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

سبب استخدام الحِزم للمصدر الذي تم إنشاؤه

على عكس برامج التحويل البرمجي C/C++، لا يقبل rustc سوى ملف مصدر واحد يمثّل نقطة دخول إلى ملف ثنائي أو مكتبة. ويفترض أن تكون شجرة المصدر مُنظَّمة بحيث يمكن اكتشاف جميع ملفات المصدر المطلوبة تلقائيًا. وهذا يعني أنّه يجب وضع المصدر الذي تم إنشاؤه في شجرة المصدر أو تقديمه من خلال توجيه include في المصدر:

include!("/path/to/hello.rs");

يعتمد مجتمع Rust على build.rs النصوص البرمجية والافتراضات حول بيئة إنشاء Cargo من أجل التعامل مع هذا الاختلاف. عند إنشاء الإصدار، يضبط الأمر cargo متغيّر البيئة OUT_DIR الذي من المتوقّع أن تضع فيه نصوص build.rs البرمجية رمز المصدر الذي تم إنشاؤه. استخدِم الرمز التالي لتضمين رمز المصدر:

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

يشكّل ذلك تحديًا لخدمة Soong لأنّه يتم وضع نواتج كل وحدة في دليل out/ الخاص بها¹. لا يتوفّر OUT_DIR واحد حيث تُخرج التبعيات المصدر الذي تم إنشاؤه.

بالنسبة إلى رمز النظام الأساسي، يفضّل AOSP تجميع المصدر الذي تم إنشاؤه في حزمة يمكن استيرادها، وذلك لعدة أسباب:

• منع تطابق أسماء الملفات المصدر التي تم إنشاؤها
• قلِّل من الرموز البرمجية النموذجية التي تم تسجيلها في جميع أنحاء الشجرة وتتطلّب الصيانة. يمكن الاحتفاظ بشكل مركزي بأي نموذج مطلوب لتجميع المصدر الذي تم إنشاؤه في حزمة.
• تجنَّب التفاعلات الضمنية² بين الرمز الذي تم إنشاؤه والمجموعة المحيطة به.
• يمكنك تقليل الضغط على الذاكرة والقرص من خلال الربط الديناميكي بالمصادر المنشأة الشائعة الاستخدام.

نتيجةً لذلك، تُنشئ جميع أنواع وحدات إنشاء رمز المصدر باستخدام Rust في Android رمزًا يمكن تجميعه واستخدامه كحزمة. لا يزال Soong متوافقًا مع حِزم الجهات الخارجية بدون تعديل إذا تم نسخ كل ملفات الاعتماد المصدرية التي تم إنشاؤها لوحدة إلى ملف واحد لكل وحدة، على غرار Cargo. في هذه الحالات، يضبط Soong متغيّر البيئة OUT_DIR على هذا الدليل عند تجميع الوحدة، حتى يمكن العثور على المصدر الذي تم إنشاؤه. ومع ذلك، ولأسباب سبق توضيحها، من أفضل الممارسات عدم استخدام هذه الآلية في رمز المنصة إلا عند الضرورة القصوى.