تنسيق ملف 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 الذي يتم إنشاؤه من خلال تشغيل m soong_docs. سيكون الناتج في out/soong/docs/soong_build.html.

الأنواع

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

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

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

الأنماط العامة

يمكن أن تأخذ الخصائص التي تأخذ قائمة ملفات، مثل srcs، أنماطًا عامة أيضًا. يمكن أن تحتوي الأنماط العامة على حرف البدل العادي *، مثلاً *.java. يمكن أن تحتوي الأنماط العامة أيضًا على حرف بدل واحد ** كعنصر مسار، والذي يطابق صفرًا أو أكثر من عناصر المسار. على سبيل المثال، يطابق النمط 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 .

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