مرجع إعدادات Lightbuild

تتكوّن إعدادات التصميم في مشروع Lightbuild من ملفات YAML: ملف project.lightbuild.yaml في الدليل الجذري للمشروع، وملف lightbuild.yaml في كل وحدة. توضّح هذه الصفحة الإعدادات في كل ملف.

ملف المشروع

تتوفّر إعدادات المشروع العامة في ملف project.lightbuild.yaml في الدليل الجذري لمشروعك. على سبيل المثال:

project:
  name: MyApp

modules:
  - app
  - app-core

repositories:
  - google
  - mavenCentral

lightbuild:
  version: 0.0.30

build:
  java:
    version: 17
  kotlin:
    version: 2.3.20
  jvmTarget: "17"

يوضّح الجدول التالي هذه الإعدادات:

الإعداد الوصف
project.name اسم المشروع، على سبيل المثال MyApp يعرض "استوديو Android" هذا الاسم كجذر نافذة المشروع. وعلى غرار rootProject.name في Kotlin DSL، يكون هذا الاسم منفصلاً عن اسم تطبيقك ومعرّف التطبيق.
modules الوحدات في المشروع، مثل وحدة التطبيق (app) ووحدات المكتبة (app-core).
repositories المستودعات البعيدة التي يحلّ Lightbuild التبعيات منها لمعرفة التفاصيل، يُرجى الاطّلاع على المستودعات.
lightbuild.version إصدار Lightbuild الذي يستخدمه المشروع
build.kotlin.version إصدار Kotlin الذي يستخدمه المشروع
build.java.version إصدار برنامج تجميع Java الذي يتطلبه المشروع
build.jvmTarget الإصدار المستهدَف من رمز بايت آلة جافا الافتراضية (JVM) الذي تم إنشاؤه

المستودعات

استخدِم repositories لعرض المستودعات التي يحلّ Lightbuild التبعيات منها. يمكنك إدراج مستودعات google وmavenCentral المضمّنة، وإضافة مستودعات Maven مخصّصة باستخدام maven:

repositories:
  - google
  - mavenCentral
  - maven:
      name: "Example Repo"
      url: "https://maven.example.com/releases"

يتضمّن مستودع maven الإعدادات التالية:

الإعداد الوصف
name اسم المستودع
url عنوان URL الخاص بالمستودع
credentials اختيارية: المفاتيح التي ترتبط باسم المستخدم وكلمة المرور للمستودع في ملف local.properties لمعرفة التفاصيل، يُرجى الاطّلاع على بيانات اعتماد المستودع.

بيانات اعتماد المستودع

إذا كان مستودع Maven يتطلّب اسم مستخدم وكلمة مرور، أضِف مجموعة credentials إلى المستودع. لا تمثّل القيمتان username وpassword بيانات الاعتماد نفسها، بل هما مفتاحان تحدّدهما في ملف local.properties الخاص بمشروعك:

repositories:

  - google
  - mavenCentral
  - maven:
      name: "Internal Repo"
      url: "https://maven.example.com/releases"
      credentials:
        username: internalRepoUser
        password: internalRepoPassword

بعد ذلك، في ملف local.properties الخاص بمشروعك، اربط كل مفتاح بقيمته. استبدِل REPO_USERNAME وREPO_PASSWORD ببيانات الاعتماد الخاصة بك:

# Also define sdk.dir, the path to your Android SDK.
internalRepoUser=REPO_USERNAME
internalRepoPassword=REPO_PASSWORD

ملفات الوحدة

يحتوي كلّ مكوّن على ملف lightbuild.yaml في دليله يحدّد إعدادات المكوّن. يوضّح الجدول التالي الإعدادات على المستوى الأعلى:

الإعداد الوصف
platform النظام الأساسي الذي تستهدفه الوحدة: android
type نوع الوحدة: application لوحدة التطبيق، أو library لوحدة المكتبة. لمزيد من المعلومات، يُرجى الاطّلاع على بنية مشروع Lightbuild.
optionalFeatures الميزات الاختيارية التي يمكن تفعيلها للوحدة، مثل com.android.tools.lightbuild.protobuf لدعم Protocol Buffers. لمعرفة التفاصيل، يُرجى الاطّلاع على Protocol Buffers.
android إعدادات Android للوحدة لمعرفة التفاصيل، يُرجى الاطّلاع على إعدادات Android.

إعدادات Android

يحتوي قسم android على إعدادات إصدار Android للوحدة:

الإعداد الوصف
namespace مساحة الاسم الخاصة بالوحدة لمزيد من المعلومات، يُرجى الاطّلاع على ضبط مساحة الاسم.
compileSdk مستوى واجهة برمجة التطبيقات الذي يتم تجميع الوحدة على أساسه لمعرفة التفاصيل، يُرجى الاطّلاع على إصدارات حزمة تطوير البرامج (SDK).
minSdk الحدّ الأدنى لمستوى واجهة برمجة التطبيقات الذي تتوافق معه الوحدة
targetSdk مستوى واجهة برمجة التطبيقات الذي يستهدفه التطبيق تتوفّر هذه الميزة في وحدات التطبيق فقط.
applicationId معرّف التطبيق يتم ضبطها في وحدات التطبيق.
versionCode رمز إصدار التطبيق يتم ضبطها في وحدات التطبيق.
versionName اسم إصدار التطبيق يتم ضبطها في وحدات التطبيق.
packaging إعدادات حِزم إصدارات debug وrelease للتطبيق، مثل توقيع الإصدار تتوفّر هذه الميزة في وحدة التطبيق فقط. لمزيد من التفاصيل، يُرجى الاطّلاع على التعبئة.
dependencies اعتماديات الوحدة على الوحدات الأخرى والمكتبات الخارجية لمعرفة التفاصيل، يُرجى الاطّلاع على التبعيات.
kspProcessors معالِجات KSP التي تنشئ الرمز البرمجي للوحدة لمعرفة التفاصيل، يُرجى الاطّلاع على معالِجات KSP.
tests الاختبارات المحلية واختبارات قياس حالة التطبيق للوحدة لمعرفة التفاصيل، يُرجى الاطّلاع على الاختبارات.

إصدارات حزمة تطوير البرامج (SDK)

حدِّد إعدادات compileSdk وminSdk وtargetSdk كمستويات واجهة برمجة التطبيقات ضمن version.release.apiLevel. على سبيل المثال، تعمل الإعدادات التالية على تجميع الوحدة وفقًا للمستوى 36 من واجهة برمجة التطبيقات، وتتيح المستوى 24 من واجهة برمجة التطبيقات والإصدارات الأحدث، وتستهدف المستوى 36 من واجهة برمجة التطبيقات:

android:
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  targetSdk:
    version:
      release:
        apiLevel: 36

تتيح وحدات التطبيق فقط استخدام الإعداد targetSdk. تحدّد وحدات المكتبة إعدادات compileSdk وminSdk فقط.

الطلبات التابعة

حدِّد اعتماديات الوحدة في الحزمة dependencies:

  • module: الوحدات الأخرى في مشروعك، مكتوبة على النحو التالي // متبوعة باسم الوحدة، على سبيل المثال //app-core أو //features/search.
  • ‫maven: المكتبات الخارجية، المكتوبة كإحداثيات Maven بالتنسيق group:artifact:version.

على سبيل المثال، تضيف الإعدادات التالية تبعيات على وحدة app-core وعلى مكتبة AndroidX Core KTX:

android:
  dependencies:
    module:
      - //app-core
    maven:
      - androidx.core:core-ktx:1.18.0

إعدادات التبعية

By default, a module compiles against each of its dependencies and includes them at runtime, but doesn't expose them to the modules that depend on it. لتغيير طريقة استخدام الوحدة لتبعية معيّنة، أضِف نقطتَين رأسيتَين بعد التبعية، ثم أضِف إعداد compile أو إعداد runtime أو كليهما أسفلها:

android:
  dependencies:
    module:
      - //data:
          compile: public
    maven:
      - androidx.core:core-ktx:1.18.0
      - androidx.annotation:annotation:1.9.1:
          runtime: off

في هذا المثال، يمكن للوحدات التي تعتمد على هذه الوحدة أيضًا استخدام فئات الوحدة data. يتم استخدام مكتبة Jetpack Annotation فقط لتجميع هذه الوحدة. يستخدم Core KTX الإعدادات التلقائية.

يتحكّم الإعداد compile في الوحدات التي يتم تجميعها وفقًا للتبعية:

  • ‫private (تلقائي): يتم تجميع هذه الوحدة وفقًا للاعتمادية، ولكن لا يتم تجميع الوحدات التي تعتمد على هذه الوحدة.
  • ‫public: يتم تجميع هذه الوحدة والوحدات التي تعتمد عليها وفقًا للتبعية. استخدِم public عندما تستخدم واجهة برمجة التطبيقات العامة للوحدة أنواعًا من التبعية.
  • ‫off: لا يتم تجميع هذه الوحدة مع التبعية.

يتحكّم الإعداد runtime في ما إذا كانت التبعية متاحة في وقت التشغيل:

  • public (تلقائي): تكون التبعية متاحة في وقت التشغيل لهذه الوحدة والوحدات التي تعتمد عليها.
  • ‫off: التبعية غير متاحة في وقت التشغيل. استخدِم off للتبعيات التي يحتاجها الرمز البرمجي فقط في وقت التجميع، مثل التعليقات التوضيحية.

لا يمكن أن تكون قيمة كل من compile وruntime هي off. في تبعيات الاختبار، يمكن أن يكون compile فقط private أو off.

لمعرفة مدى توافق هذه الإعدادات مع إعدادات Kotlin DSL، مثل api وcompileOnly، يُرجى الاطّلاع على مقارنة Lightbuild مع Kotlin DSL.

معالِجات KSP

لاستخدام أداة إنشاء رموز برمجية تستند إلى معالجة رموز Kotlin‏ (KSP)، مثل Moshi أو Room، أضِف المعالج إلى مجموعة kspProcessors، وأضِف المكتبات التي يستخدمها الرمز البرمجي في وقت التشغيل إلى مجموعة dependencies. يطبّق Lightbuild تلقائيًا المكوّن الإضافي KSP ويضبط إنشاء الرموز البرمجية أثناء عملية الإنشاء.

على سبيل المثال، تضبط الإعدادات التالية Moshi باستخدام أداة إنشاء الرموز البرمجية KSP:

android:
  dependencies:
    maven:
      - com.squareup.moshi:moshi:1.15.2
      - com.squareup.moshi:moshi-kotlin:1.15.2
  kspProcessors:
    maven:
      - com.squareup.moshi:moshi-kotlin-codegen:1.15.2

Protocol Buffers

لإنشاء رمز من ملفات Protocol Buffers (.proto) في وحدة مكتبة، أضِف ميزة Protocol Buffers إلى قائمة optionalFeatures في الوحدة، وأضِف مكتبات وقت تشغيل Protocol Buffers إلى تبعيات الوحدة. ‫optionalFeatures هو إعداد من المستوى الأعلى، خارج مجموعة android:

optionalFeatures:
  - com.android.tools.lightbuild.protobuf

android:
  dependencies:
    maven:
      - com.google.protobuf:protobuf-javalite:4.28.2
      - com.google.protobuf:protobuf-kotlin-lite:4.28.2

ضَع ملفات .proto الخاصة بالوحدة في دليل src/main/proto. عند إنشاء الوحدة، تنشئ Lightbuild فئات Java وKotlin لبيئة التشغيل البسيطة لـ Protocol Buffers، والتي يُنصح باستخدامها مع Android.

الاختبارات

اضبط اختبارات الوحدة في الحزمة tests:

  • ‫test: الاختبارات المحلية التي يتم إجراؤها على جهاز Java الافتراضي (JVM) في جهاز التطوير أدرِج تبعيات الاختبارات ضمن dependencies.
  • ‫androidTest: اختبارات لقياس حالة التطبيق يتم إجراؤها على جهاز أو محاكي اضبط runner على فئة مشغّل الاختبار، وأدرِج تبعيات الاختبارات ضمن dependencies.

على سبيل المثال:

android:
  tests:
    test:
      dependencies:
        maven:
          - junit:junit:4.13.2
    androidTest:
      runner: androidx.test.runner.AndroidJUnitRunner
      dependencies:
        maven:
          - androidx.test.ext:junit:1.3.0
          - androidx.test.espresso:espresso-core:3.7.0

حزمة المحتوى

في وحدات التطبيق، استخدِم مجموعة packaging لضبط إصدارات debug وrelease للتطبيق. لتوقيع بنية الإصدار باستخدام مفتاحك الخاص، أضِف مجموعة signing إلى ملف release الشخصي:

android:
  packaging:
    release:
      signing:
        storeFile: "${RELEASE_STORE_FILE}"
        storePassword: "${RELEASE_STORE_PASSWORD}"
        keyAlias: "${RELEASE_KEY_ALIAS}"
        keyPassword: "${RELEASE_KEY_PASSWORD}"

تتيح وحدة signing الإعدادات التالية:

  • ‫storeFile: مسار ملف مخزن المفاتيح، إما بالنسبة إلى دليل الوحدة أو يبدأ بـ ~/ لموقع في الدليل الرئيسي.
  • ‫storePassword: كلمة مرور مخزن المفاتيح
  • ‫keyAlias: الاسم المستعار لمفتاح التوقيع في مخزن المفاتيح.
  • ‫keyPassword: كلمة مرور مفتاح التوقيع

لإبقاء كلمات المرور خارج ملفات مشروعك، اضبط هذه القيم على مراجع متغيّرات البيئة باستخدام بنية ${NAME}، كما هو موضّح في المثال. يمكنك كتابة storeFile وkeyAlias مباشرةً، أو الإشارة إلى متغيرات البيئة لهما أيضًا. عند إنشاء التطبيق، تستبدل Lightbuild كل مرجع بقيمة متغيّر البيئة. يجب أن تحتوي كل قيمة على المرجع فقط: لا يستبدل Lightbuild مرجعًا يشكّل جزءًا من قيمة أطول، مثل ${HOME}/upload-keystore.jks.

أمثلة

تعرض الأمثلة التالية ملفات وحدة كاملة لوحدة تطبيق ووحدة مكتبة.

وحدة التطبيق

يضبط ملف app/lightbuild.yaml التالي وحدة تطبيق تعتمد على وحدة مكتبة app-core:

platform: android
type: application
android:
  namespace: com.example.myapp.app
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  targetSdk:
    version:
      release:
        apiLevel: 36
  applicationId: com.example.myapp
  versionCode: 1
  versionName: "1.0"
  dependencies:
    module:
      - //app-core

وحدة المكتبة

يضبط ملف app-core/lightbuild.yaml التالي وحدة مكتبة تستخدم Jetpack Compose وMoshi وتحتوي على اختبارات محلية واختبارات لقياس حالة التطبيق:

platform: android
type: library
android:
  namespace: com.example.myapp
  compileSdk:
    version:
      release:
        apiLevel: 36
  minSdk:
    version:
      release:
        apiLevel: 24
  dependencies:
    maven:
      - androidx.core:core-ktx:1.18.0
      - androidx.lifecycle:lifecycle-runtime-ktx:2.10.0
      - androidx.activity:activity-compose:1.13.0
      - androidx.lifecycle:lifecycle-runtime-compose:2.10.0
      - androidx.lifecycle:lifecycle-viewmodel-compose:2.10.0
      - androidx.compose.ui:ui:1.10.4
      - androidx.compose.ui:ui-tooling-preview:1.10.4
      - androidx.compose.material3:material3:1.4.0
      - androidx.navigation3:navigation3-ui:1.0.1
      - androidx.navigation3:navigation3-runtime:1.0.1
      - androidx.lifecycle:lifecycle-viewmodel-navigation3:2.10.0
      - androidx.compose.ui:ui-tooling:1.10.4
      - androidx.compose.ui:ui-test-manifest:1.10.4
      - com.squareup.moshi:moshi:1.15.2
      - com.squareup.moshi:moshi-kotlin:1.15.2
  kspProcessors:
    maven:
      - com.squareup.moshi:moshi-kotlin-codegen:1.15.2
  tests:
    test:
      dependencies:
        maven:
          - junit:junit:4.13.2
          - org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2
    androidTest:
      runner: androidx.test.runner.AndroidJUnitRunner
      dependencies:
        maven:
          - androidx.test:core:1.7.0
          - androidx.test.ext:junit:1.3.0
          - androidx.test:runner:1.7.0
          - androidx.test.espresso:espresso-core:3.7.0
          - androidx.compose.ui:ui-test-junit4:1.10.4