قالب فایل 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 فایل‌های منبع استفاده‌شده برای ساختن ماژول را به‌صورت فهرستی از رشته‌ها مشخص می‌کند. می‌توانید بااستفاده از نحو مرجع واحد ":<module-name>"، به برونداد واحدهای دیگری که فایل‌های منبع تولید می‌کنند، مانند genrule یا filegroup، ارجاع دهید.

برای مشاهده فهرست انواع معتبر ماژول و ویژگی‌های آن‌ها، به «مرجع ماژول‌های Soong» که با اجرای m soong_docs تولید شده است مراجعه کنید. برونداد به زبان out/soong/docs/soong_build.html خواهد بود.

انواع

متغیرها و ویژگی‌ها به‌شدت تایپ می‌شوند، به‌طوری‌که متغیرها به‌صورت پویا براساس اولین تخصیص و ویژگی‌ها به‌صورت ایستا توسط نوع ماژول تنظیم می‌شوند. انواع پشتیبانی‌شده عبارت‌اند از:

• بولی (true یا false)
• اعداد صحیح (int)
• رشته‌ها ("string")
• فهرست‌های رشته‌ها (["string1", "string2"])
• Maps ({key1: "value1", key2: ["value2"]})

نگاشت‌ها می‌توانند شامل مقادیری از هر نوع باشند، ازجمله نگاشت‌های تودرتو. فهرست‌ها و نقشه‌ها ممکن است بعداز آخرین مقدار، ویرگول پایانی داشته باشند.

حباب‌ها

ویژگی‌هایی که فهرستی از فایل‌ها را می‌گیرند، مثل 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 .

قالب متعارف شامل تورفتگی‌های چهار فاصله‌ای، خطوط جدید پس‌از هر عنصر فهرست چندعنصری، و ویرگول پایانی در فهرست‌ها و نقشه‌ها است.