הפניה להגדרות של Lightbuild

תצורת ה-build של פרויקט 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 Studio כשורש של החלון Project. בדומה ל-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 לתמיכה במאגרי אחסון לפרוטוקולים. לפרטים נוספים, ראו מאגרי אחסון לפרוטוקולים.
android הגדרות Android של המודול. פרטים נוספים זמינים במאמר הגדרות Android.

הגדרות Android

הבלוק android מכיל את הגדרות ה-build של המודול ל-Android:

הגדרה תיאור
namespace מרחב השמות של המודול. מידע נוסף זמין בקטע הגדרת מרחב השמות.
compileSdk רמת ה-API שלפיה המודול מקומפל. פרטים נוספים זמינים במאמר גרסאות SDK.
minSdk רמת ה-API המינימלית שהמודול תומך בה.
targetSdk רמת ה-API שהאפליקציה מטרגטת. נתמך רק במודולים של אפליקציות.
applicationId מזהה האפליקציה. הגדרת מודולים באפליקציה.
versionCode קוד הגרסה של האפליקציה. הגדרת מודולים באפליקציה.
versionName שם הגרסה של האפליקציה. הגדרת מודולים באפליקציה.
packaging הגדרות לאריזת גרסאות ה-Build של האפליקציה ל-debug ול-release, כמו חתימה על גרסאות. נתמך רק במודול של האפליקציה. פרטים נוספים זמינים במאמר בנושא אריזה.
dependencies התלות של המודול במודולים אחרים ובספריות חיצוניות. לפרטים נוספים, קראו את המאמר יחסי תלות.
kspProcessors מעבדי ה-KSP שיוצרים קוד למודול. פרטים נוספים זמינים במאמר מעבדי KSP.
tests הבדיקות המקומיות ובדיקות האינסטרומנטציה של המודול. פרטים נוספים זמינים במאמר בדיקות.

גרסאות SDK

מציינים את ההגדרות של compileSdk,‏ minSdk ו-targetSdk כרמות API בקטע version.release.apiLevel. לדוגמה, ההגדרות הבאות מקמפלות את המודול בהתאם לרמת API‏ 36, תומכות ברמת API‏ 24 ומעלה ומטרגטות לרמת ה-API המיועדת 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

הגדרות תלות

כברירת מחדל, מודול מקמפל את כל יחסי התלות שלו וכולל אותם בזמן הריצה, אבל לא חושף אותם למודולים שתלויים בו. כדי לשנות את האופן שבו מודול משתמש ביחסי תלות, מוסיפים נקודתיים אחרי יחסי התלות, ואז מוסיפים את ההגדרה 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 כשה-API הציבורי של המודול משתמש בסוגים מהתלות.
  • ‫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 ומגדיר את יצירת הקוד במהלך ה-build.

לדוגמה, ההגדרות הבאות מגדירות את 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 כדי להגדיר את ה-builds של debug ו-release באפליקציה. כדי לחתום על גרסת ה-build להפצה באמצעות מפתח משלכם, מוסיפים בלוק 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 ישירות, או להפנות למשתני סביבה גם עבורם. כשיוצרים build, ‏ 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