ข้อมูลอ้างอิงการกำหนดค่า 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"

ตารางต่อไปนี้จะอธิบายการตั้งค่าเหล่านี้

ที่เก็บ

ใช้ repositories เพื่อแสดงรายการที่เก็บที่ Lightbuild แก้ไขทรัพยากร Dependency คุณสามารถแสดงรายการที่เก็บ google และ mavenCentral ในตัว และเพิ่มที่เก็บ Maven ที่กำหนดเองด้วย maven:

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

ที่เก็บ maven มีการตั้งค่าต่อไปนี้

ข้อมูลเข้าสู่ระบบของที่เก็บ

หากที่เก็บ 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 ในไดเรกทอรีที่กำหนดการตั้งค่าของโมดูล ตารางต่อไปนี้จะอธิบายการตั้งค่าระดับบนสุด

การตั้งค่า Android

บล็อก android มีการตั้งค่าบิลด์ Android ของโมดูล ดังนี้

เวอร์ชัน 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 เท่านั้น

ความสัมพันธ์

ประกาศทรัพยากร Dependency ของโมดูลในบล็อก dependencies ดังนี้

• module: โมดูลอื่นๆ ในโปรเจ็กต์ ซึ่งเขียนเป็น // ตามด้วยชื่อโมดูล เช่น //app-core หรือ //features/search
• maven: ไลบรารีภายนอกที่เขียนเป็นพิกัด Maven ในรูปแบบ group:artifact:version

ตัวอย่างเช่น การตั้งค่าต่อไปนี้จะเพิ่มทรัพยากร Dependency ในโมดูล app-core และในไลบรารี AndroidX Core KTX

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

การตั้งค่าการขึ้นต่อกัน

โดยค่าเริ่มต้น โมดูลจะคอมไพล์ตามทรัพยากร Dependency แต่ละรายการและรวมไว้ที่รันไทม์ แต่จะไม่แสดงต่อโมดูลที่ขึ้นอยู่กับโมดูลนั้น หากต้องการเปลี่ยนวิธีที่โมดูลใช้ทรัพยากร Dependency ให้เพิ่มโคลอนหลังทรัพยากร Dependency แล้วเพิ่มการตั้งค่า compile, การตั้งค่า runtime หรือทั้ง 2 อย่างด้านล่าง

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 จะควบคุมโมดูลที่คอมไพล์กับทรัพยากร Dependency ดังนี้

• private (ค่าเริ่มต้น): โมดูลนี้จะคอมไพล์โดยอิงตามทรัพยากร Dependency แต่โมดูลที่ขึ้นอยู่กับโมดูลนี้จะไม่คอมไพล์
• public: โมดูลนี้และโมดูลที่ขึ้นอยู่กับโมดูลนี้จะคอมไพล์โดยอิงตามทรัพยากร Dependency ใช้ public เมื่อ API สาธารณะของโมดูลใช้ประเภทจากการขึ้นต่อกัน
• off: โมดูลนี้ไม่คอมไพล์กับทรัพยากร Dependency

การตั้งค่า runtime จะควบคุมว่าทรัพยากร Dependency พร้อมใช้งานที่รันไทม์หรือไม่

• public (ค่าเริ่มต้น): ทรัพยากร Dependency พร้อมใช้งานที่รันไทม์สำหรับโมดูลนี้และโมดูลที่ขึ้นอยู่กับโมดูลนี้
• off: ทรัพยากร Dependency ไม่พร้อมใช้งานที่รันไทม์ ใช้ off สำหรับทรัพยากร Dependency ที่โค้ดของคุณต้องการเฉพาะในเวลาคอมไพล์ เช่น คำอธิบายประกอบ

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 ของโมดูล และเพิ่มไลบรารีรันไทม์ของบัฟเฟอร์โปรโตคอลลงในทรัพยากร Dependency ของโมดูล 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 สำหรับรันไทม์ Lite ของบัฟเฟอร์โปรโตคอล ซึ่งเป็นรันไทม์ที่แนะนำสำหรับ Android

การทดสอบ

กำหนดค่าการทดสอบของโมดูลในบล็อก tests ดังนี้

• test: การทดสอบในเครื่องที่ทำงานบน JVM ของคอมพิวเตอร์สำหรับการพัฒนาซอฟต์แวร์ แสดงรายการทรัพยากร Dependency ของการทดสอบในส่วน dependencies
• androidTest: การทดสอบที่มีการวัดคุมซึ่งทำงานในอุปกรณ์หรือโปรแกรมจำลอง ตั้งค่า runner เป็นคลาส Test Runner และแสดงรายการทรัพยากร Dependency ของการทดสอบในส่วน 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: รหัสผ่านของ Keystore
• keyAlias: ชื่อแทนของคีย์ Signing ใน Keystore
• keyPassword: รหัสผ่านของคีย์ Signing

หากต้องการเก็บรหัสผ่านไว้นอกไฟล์ของโปรเจ็กต์ ให้ตั้งค่าเหล่านี้เป็นการอ้างอิงตัวแปรสภาพแวดล้อมด้วยไวยากรณ์ ${NAME} ดังตัวอย่าง คุณสามารถเขียน storeFile และ keyAlias ได้โดยตรง หรือจะอ้างอิงตัวแปรสภาพแวดล้อมสำหรับทั้ง 2 รายการก็ได้เช่นกัน เมื่อคุณสร้าง 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