تنسيق ملف Android.bp

بشكل عام، تكون ملفات Android.bp بسيطة. ولا تحتوي على عبارات شرطية أو عبارات للتحكّم في سير العمل، بل يتم التعامل مع جميع التعقيدات من خلال منطق الإنشاء المكتوب بلغة Go.

الوحدات

يبدأ القسم في ملف Android.bp بنوع القسم متبوعًا بمجموعة من السمات بتنسيق name: "value",:

cc_binary {
    name: "gzip",
    srcs: ["src/test/minigzip.c"],
    shared_libs: ["libz"],
    stl: "none",
}

يجب أن يحتوي كل نموذج على السمة name، ويجب أن تكون القيمة فريدة في جميع ملفات Android.bp، باستثناء قيم السمة name في مساحات الأسماء والوحدات المسبقة الإنشاء، والتي قد تتكرر.

تحدّد السمة srcs الملفات المصدر المستخدَمة لإنشاء الوحدة النمطية، وذلك كقائمة من السلاسل. يمكنك الرجوع إلى ناتج الوحدات الأخرى التي تنتج ملفات مصدر، مثل genrule أو filegroup، باستخدام بنية مرجع الوحدة ":<module-name>".

للاطّلاع على قائمة بأنواع الوحدات الصالحة وخصائصها، يُرجى الرجوع إلى مرجع وحدات Soong.

الأنواع

تكون المتغيرات والخصائص ذات أنواع محددة بدقة، مع تحديد المتغيرات ديناميكيًا استنادًا إلى عملية التعيين الأولى، وتحديد الخصائص بشكل ثابت حسب نوع الوحدة. الأنواع المتوافقة هي:

• قيم منطقية (true أو false)
• الأعداد الصحيحة (int)
• السلاسل ("string")
• قوائم السلاسل (["string1", "string2"])
• الخرائط ({key1: "value1", key2: ["value2"]})

قد تحتوي الخرائط على قيم من أي نوع، بما في ذلك الخرائط المتداخلة. قد تحتوي القوائم والخرائط على فواصل لاحقة بعد القيمة الأخيرة.

Globs

يمكن أن تقبل السمات التي تتضمّن قائمة بالملفات، مثل srcs، أنماط glob أيضًا. يمكن أن تحتوي أنماط Glob على حرف البدل العادي * في نظام التشغيل UNIX، مثل *.java. يمكن أن تحتوي أنماط Glob أيضًا على حرف بدل ** واحد كعنصر مسار، والذي يطابق صفرًا أو أكثر من عناصر المسار. على سبيل المثال، يتطابق java/**/*.java مع النمطَين java/Main.java وjava/com/android/Main.java.

المتغيّرات

قد يحتوي ملف Android.bp على عمليات تعيين متغيّرات من المستوى الأعلى:

gzip_srcs = ["src/test/minigzip.c"],
cc_binary {
    name: "gzip",
    srcs: gzip_srcs,
    shared_libs: ["libz"],
    stl: "none",
}

يتم تحديد نطاق المتغيرات ببقية الملف الذي تم تعريفها فيه، بالإضافة إلى أي ملفات Blueprint فرعية. المتغيرات غير قابلة للتغيير باستثناء حالة واحدة، وهي أنّه يمكن إضافة قيمة إلى المتغير باستخدام عملية تعيين +=، ولكن فقط قبل الإشارة إلى المتغير.

التعليقات

يمكن أن تحتوي ملفات Android.bp على تعليقات متعددة الأسطر بتنسيق C /* */ وتعليقات أحادية الأسطر بتنسيق C++ //.

عوامل التشغيل

يمكن إلحاق السلاسل وقوائم السلاسل والخرائط باستخدام عامل التشغيل +. يمكن جمع الأعداد الصحيحة باستخدام عامل التشغيل +. يؤدي إلحاق خريطة إلى إنتاج اتحاد المفاتيح في كلتا الخريطتين، وإلحاق قيم أي مفاتيح متوفرة في كلتا الخريطتين.

وحدات الإعدادات التلقائية

يمكن للمطوّرين استخدام وحدة تلقائية لتكرار الخصائص نفسها في وحدات متعددة. مثلاً:

cc_defaults {
    name: "gzip_defaults",
    shared_libs: ["libz"],
    stl: "none",
}

cc_binary {
    name: "gzip",
    defaults: ["gzip_defaults"],
    srcs: ["src/test/minigzip.c"],
}

الوحدات المُنشأة مسبقًا

تسمح بعض أنواع الوحدات الإنشائية المُعدّة مسبقًا بأن يكون للوحدة الإنشائية الاسم نفسه المستخدَم في الوحدات الإنشائية المشابهة المستندة إلى المصدر. على سبيل المثال، يمكن أن يكون هناك cc_prebuilt_binary باسم foo عندما يكون هناك cc_binary بالاسم نفسه. ويمنح ذلك المطوّرين المرونة في اختيار النسخة التي يريدون تضمينها في المنتج النهائي. إذا كان إعداد الإصدار يتضمّن كلا الإصدارين، فإنّ قيمة العلامة prefer في تعريف الوحدة النمطية المُنشأة مسبقًا تحدّد الإصدار الذي له الأولوية. يُرجى العِلم أنّ بعض الوحدات المبرمَجة مسبقًا لها أسماء لا تبدأ بـ prebuilt، مثل android_app_import.

وحدات مساحة الاسم

إلى أن يتم تحويل Android بالكامل من Make إلى Soong، يجب أن يحدّد إعداد المنتج في Make قيمة PRODUCT_SOONG_NAMESPACES. يجب أن تكون قيمته قائمة بأسماء النطاقات مفصولة بمسافات، ويتم تصديرها من Soong إلى Make ليتم إنشاؤها باستخدام الأمر m. بعد اكتمال عملية نقل Android إلى Soong، قد تتغيّر تفاصيل تفعيل مساحات الأسماء.

تتيح أداة Soong إمكانية أن تحدّد الوحدات في الدلائل المختلفة الاسم نفسه، طالما تم الإعلان عن كل وحدة ضمن مساحة اسم منفصلة. ويمكن للمطوّرين الإعلان عن مساحة اسم باتّباع الخطوات التالية:

soong_namespace {
    imports: ["path/to/otherNamespace1", "path/to/otherNamespace2"],
}

يُرجى العِلم أنّ مساحة الاسم لا تتضمّن السمة name، ويتم تلقائيًا تعيين مسارها كاسم لها.

يتم تخصيص مساحة اسم لكل وحدة Soong استنادًا إلى موقعها في الشجرة. يُعدّ كل وحدة Soong ضمن مساحة الاسم المحدّدة بواسطة soong_namespace الموجودة في ملف Android.bp في الدليل الحالي أو دليل الأصل الأقرب. إذا لم يتم العثور على وحدة soong_namespace من هذا النوع، سيتم اعتبار الوحدة في مساحة الاسم الجذر الضمنية.

في ما يلي مثال: تحاول أداة Soong تحليل التبعية D التي تم تعريفها بواسطة الوحدة M في مساحة الاسم N التي تستورد مساحات الأسماء I1 وI2 وI3…

1. بعد ذلك، إذا كان D اسمًا مؤهلاً بالكامل بالشكل //namespace:module، سيتم البحث عن اسم الوحدة النمطية المحدّد في مساحة الاسم المحدّدة فقط.
2. بخلاف ذلك، يبحث Soong أولاً عن وحدة باسم D معرَّفة في مساحة الاسم N.
3. إذا لم تكن هذه الوحدة النمطية متوفّرة، يبحث Soong عن وحدة نمطية باسم D في مساحات الأسماء I1 وI2 وI3 وما إلى ذلك.
4. يبحث Soong في مساحة الاسم الجذر.

العبارات الشرطية

لا يتيح Soong استخدام عبارات شرطية في ملفات Android.bp. بدلاً من ذلك، يتم التعامل مع التعقيد في قواعد الإنشاء التي تتطلّب عبارات شرطية في Go، حيث يمكن استخدام ميزات اللغة عالية المستوى، ويمكن تتبُّع التبعيات الضمنية التي تقدّمها العبارات الشرطية. يتم تحويل معظم العبارات الشرطية إلى سمة خريطة، حيث يتم اختيار إحدى القيم في الخريطة وإلحاقها بالسمات ذات المستوى الأعلى.

على سبيل المثال، لدعم الملفات الخاصة بالبنية:

cc_library {
    ...
    srcs: ["generic.cpp"],
    arch: {
        arm: {
            srcs: ["arm.cpp"],
        },
        x86: {
            srcs: ["x86.cpp"],
        },
    },
}

أداة التنسيق

يتضمّن Soong أداة تنسيق أساسية لملفات Blueprint، على غرار gofmt. لإعادة تنسيق جميع ملفات Android.bp بشكل متكرر في الدليل الحالي، نفِّذ ما يلي:

bpfmt -w .

يتضمّن التنسيق الأساسي مسافات بادئة من أربع مسافات، وأسطرًا جديدة بعد كل عنصر في قائمة متعددة العناصر، وفاصلة لاحقة في القوائم والخرائط.