مرجع پیکربندی 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 نشانی وب مخزن.
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 برای پشتیبانی از «میان‌گیری پروتکل». برای جزئیات، به میان‌گیرهای پروتکل مراجعه کنید.
android تنظیمات Android واحد. برای جزئیات، تنظیمات Android را ببینید.

تنظیمات Android

بلوک android حاوی تنظیمات ساخت Android واحد است:

تنظیم شرح
namespace جای‌نام واحد. برای اطلاعات بیشتر، تنظیم فضای نام را ببینید.
compileSdk سطح میانای برنامه‌سازی کاربردی که واحد با آن کامپایل می‌شود. برای جزئیات، نسخه‌های کیت توسعه نرم‌افزار را ببینید.
minSdk حداقل سطح میانای برنامه‌سازی کاربردی که این واحد پشتیبانی می‌کند.
targetSdk سطح میانای برنامه‌سازی کاربردی که برنامه هدف قرار می‌دهد. فقط در ماژول‌های برنامه پشتیبانی می‌شود.
applicationId شناسه برنامه. در پیمانه‌های برنامه تنظیم شده است.
versionCode کد نسخه برنامه. در پیمانه‌های برنامه تنظیم شده است.
versionName نام نسخه برنامه. در پیمانه‌های برنامه تنظیم شده است.
packaging تنظیمات بسته‌بندی کردن ساخت‌های debug و release برنامه، مثل امضای انتشار. فقط در واحد برنامه پشتیبانی می‌شود. برای جزئیات، به بسته‌بندی مراجعه کنید.
dependencies وابستگی‌های پیمانه به پیمانه‌های دیگر و کتابخانه‌های خارجی. برای جزئیات، وابستگی‌ها را ببینید.
kspProcessors پردازنده‌های KSP که برای پیمانه کد تولید می‌کنند. برای جزئیات، به پردازشگرهای KSP مراجعه کنید.
tests آزمایش‌های محلی و ابزاری واحد. برای جزئیات، آزمایش‌ها را ببینید.

نسخه‌های SDK

تنظیمات compileSdk، minSdk، و targetSdk را به‌عنوان سطوح میانای برنامه‌سازی کاربردی در version.release.apiLevel مشخص کنید. برای مثال، تنظیمات زیر واحد را دربرابر سطح میانای برنامه‌سازی کاربردی ۳۶ کامپایل می‌کند، از سطح میانای برنامه‌سازی کاربردی ۲۴ و بالاتر پشتیبانی می‌کند، و سطح میانای برنامه‌سازی کاربردی ۳۶ را هدف قرار می‌دهد:

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

تنظیمات وابستگی

به‌طور پیش‌فرض، یک پیمانه دربرابر هریک از وابستگی‌هایش کامپایل می‌شود و آن‌ها را در زمان اجرا اضافه می‌کند، اما آن‌ها را برای پیمانه‌هایی که به آن وابسته هستند آشکار نمی‌کند. برای تغییر دادن نحوه استفاده ماژول از وابستگی، دونقطه‌ای بعداز وابستگی اضافه کنید، و سپس تنظیم 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 Symbol Processing (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

میان‌گیری پروتکل

برای تولید کد از فایل‌های میان‌گیری پروتکل (.proto) در یک مدول کتابخانه، ویژگی «میان‌گیری پروتکل» را به فهرست optionalFeatures مدول اضافه کنید و کتابخانه‌های زمان اجرای «میان‌گیری پروتکل» را به وابستگی‌های مدول اضافه کنید. 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 lite تولید می‌کند که برای Android توصیه می‌شود.

آزمایش‌ها

آزمایش‌های یک ماژول را در بلوک tests پیکربندی کنید:

  • test: آزمایش‌های محلی که در 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: مسیر فایل keystore، یا نسبت به فهرست راهنمای واحد یا با شروع از ~/ برای مکانی در فهرست راهنمای خانه شما.
  • ‫storePassword: گذرواژه keystore.
  • ‫keyAlias: نام مستعار کلید امضا در keystore.
  • 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