Tài liệu tham khảo về cấu hình Lightbuild

Cấu hình bản dựng của dự án Lightbuild bao gồm các tệp YAML: một tệp project.lightbuild.yaml trong thư mục gốc của dự án và một tệp lightbuild.yaml trong mỗi mô-đun. Trang này mô tả các chế độ cài đặt trong mỗi tệp.

Tệp dự án

Chế độ cài đặt dự án chung nằm trong tệp project.lightbuild.yaml trong thư mục gốc của dự án. Ví dụ:

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"

Bảng sau đây mô tả các chế độ cài đặt này:

Kho lưu trữ

Sử dụng repositories để liệt kê các kho lưu trữ mà Lightbuild phân giải phần phụ thuộc. Bạn có thể liệt kê các kho lưu trữ google và mavenCentral tích hợp sẵn, đồng thời thêm kho lưu trữ Maven tuỳ chỉnh bằng maven:

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

Kho lưu trữ maven có các chế độ cài đặt sau:

Thông tin đăng nhập của kho lưu trữ

Nếu kho lưu trữ Maven yêu cầu tên người dùng và mật khẩu, hãy thêm một khối credentials vào kho lưu trữ. Giá trị username và password không phải là thông tin xác thực; chúng là các khoá mà bạn xác định trong tệp local.properties của dự án:

repositories:

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

Sau đó, trong tệp local.properties của dự án, hãy liên kết từng khoá với giá trị của khoá đó. Thay thế REPO_USERNAME và REPO_PASSWORD bằng thông tin đăng nhập của bạn:

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

Tệp mô-đun

Mỗi mô-đun có một tệp lightbuild.yaml trong thư mục của mô-đun đó để xác định các chế độ cài đặt của mô-đun. Bảng sau đây mô tả các chế độ cài đặt cấp cao nhất:

Cài đặt Android

Khối android chứa các chế độ cài đặt bản dựng Android của mô-đun:

Phiên bản SDK

Chỉ định các chế độ cài đặt compileSdk, minSdk và targetSdk làm cấp độ API trong version.release.apiLevel. Ví dụ: các chế độ cài đặt sau đây biên dịch mô-đun theo cấp độ API 36, hỗ trợ cấp độ API 24 trở lên và nhắm đến cấp độ API mục tiêu 36:

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

Chỉ các mô-đun ứng dụng mới hỗ trợ chế độ cài đặt targetSdk. Mô-đun thư viện chỉ xác định chế độ cài đặt compileSdk và minSdk.

Phần phụ thuộc

Khai báo các phần phụ thuộc của mô-đun trong khối dependencies:

• module: Các mô-đun khác trong dự án của bạn, được viết dưới dạng // theo sau là tên của mô-đun, ví dụ: //app-core hoặc //features/search.
• maven: Thư viện bên ngoài, được viết dưới dạng toạ độ Maven theo định dạng group:artifact:version.

Ví dụ: các chế độ cài đặt sau đây thêm phần phụ thuộc vào mô-đun app-core và vào thư viện AndroidX Core KTX:

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

Chế độ cài đặt phần phụ thuộc

Theo mặc định, một mô-đun sẽ biên dịch theo từng phần phụ thuộc và đưa các phần phụ thuộc đó vào thời gian chạy, nhưng không hiển thị các phần phụ thuộc đó cho các mô-đun phụ thuộc vào mô-đun đó. Để thay đổi cách một mô-đun sử dụng phần phụ thuộc, hãy thêm dấu hai chấm sau phần phụ thuộc, sau đó thêm chế độ cài đặt compile, chế độ cài đặt runtime hoặc cả hai chế độ cài đặt này bên dưới:

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

Trong ví dụ này, các mô-đun phụ thuộc vào mô-đun này cũng có thể sử dụng các lớp của mô-đun data. Thư viện Chú thích Jetpack chỉ được dùng để biên dịch mô-đun này. Core KTX sử dụng chế độ cài đặt mặc định.

Chế độ cài đặt compile kiểm soát mô-đun nào biên dịch theo phần phụ thuộc:

• private (mặc định): Mô-đun này biên dịch dựa trên phần phụ thuộc, nhưng các mô-đun phụ thuộc vào mô-đun này thì không.
• public: Mô-đun này và các mô-đun phụ thuộc vào mô-đun này sẽ biên dịch dựa trên phần phụ thuộc. Sử dụng public khi API công khai của mô-đun sử dụng các loại từ phần phụ thuộc.
• off: Mô-đun này không biên dịch dựa trên phần phụ thuộc.

Chế độ cài đặt runtime kiểm soát việc phần phụ thuộc có sẵn trong thời gian chạy hay không:

• public (mặc định): Phần phụ thuộc có sẵn trong thời gian chạy, cho mô-đun này và cho các mô-đun phụ thuộc vào mô-đun này.
• off: Phần phụ thuộc không có sẵn trong thời gian chạy. Sử dụng off cho các phần phụ thuộc mà mã của bạn chỉ cần trong thời gian biên dịch, chẳng hạn như chú thích.

compile và runtime không thể cùng là off. Trong các phần phụ thuộc kiểm thử, compile chỉ có thể là private hoặc off.

Để xem các chế độ cài đặt này tương ứng như thế nào với các cấu hình Kotlin DSL như api và compileOnly, hãy xem phần So sánh Lightbuild với Kotlin DSL.

Trình xử lý KSP

Để sử dụng trình tạo mã dựa trên Kotlin Symbol Processing (KSP), chẳng hạn như Moshi hoặc Room, hãy thêm trình xử lý vào khối kspProcessors và thêm các thư viện mà mã của bạn sử dụng trong thời gian chạy vào khối dependencies. Lightbuild tự động áp dụng trình bổ trợ KSP và định cấu hình việc tạo mã trong quá trình tạo bản dựng.

Ví dụ: các chế độ cài đặt sau đây định cấu hình Moshi bằng trình tạo mã 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

Vùng đệm giao thức

Để tạo mã từ các tệp Vùng đệm giao thức (.proto) trong một mô-đun thư viện, hãy thêm tính năng Vùng đệm giao thức vào danh sách optionalFeatures của mô-đun, đồng thời thêm thư viện thời gian chạy Vùng đệm giao thức vào các phần phụ thuộc của mô-đun. optionalFeatures là chế độ cài đặt cấp cao nhất, nằm ngoài khối 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

Đặt các tệp .proto của mô-đun vào thư mục src/main/proto. Khi bạn tạo mô-đun, Lightbuild sẽ tạo các lớp Java và Kotlin cho thời gian chạy Protocol Buffers Lite, đây là lựa chọn nên dùng cho Android.

Xét nghiệm

Định cấu hình các bài kiểm thử của mô-đun trong khối tests:

• test: Chương trình kiểm thử cục bộ chạy trên JVM của máy phát triển. Liệt kê các phần phụ thuộc của chương trình kiểm thử trong dependencies.
• androidTest: Kiểm thử đo lường chạy trên thiết bị hoặc trình mô phỏng. Đặt runner thành lớp trình chạy kiểm thử và liệt kê các phần phụ thuộc của kiểm thử trong dependencies.

Ví dụ:

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

Nội dung ngữ cảnh

Trong các mô-đun ứng dụng, hãy sử dụng khối packaging để định cấu hình bản dựng debug và release của ứng dụng. Để ký bản phát hành bằng khoá của riêng bạn, hãy thêm một khối signing vào hồ sơ release:

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

Khối signing hỗ trợ các chế độ cài đặt sau:

• storeFile: Đường dẫn đến tệp kho khoá, tương ứng với thư mục của mô-đun hoặc bắt đầu bằng ~/ cho một vị trí trong thư mục gốc.
• storePassword: Mật khẩu của kho khoá.
• keyAlias: Bí danh của khoá ký trong kho khoá.
• keyPassword: Mật khẩu của khoá ký.

Để không lưu mật khẩu trong các tệp của dự án, hãy đặt các giá trị này thành tham chiếu biến môi trường bằng cú pháp ${NAME}, như trong ví dụ. Bạn có thể viết trực tiếp storeFile và keyAlias hoặc tham chiếu các biến môi trường cho các biến đó. Khi bạn tạo bản dựng, Lightbuild sẽ thay thế từng tệp tham chiếu bằng giá trị của biến môi trường. Mỗi giá trị chỉ được chứa tệp đối chiếu: Lightbuild không thay thế tệp đối chiếu là một phần của giá trị dài hơn, chẳng hạn như ${HOME}/upload-keystore.jks.

Ví dụ

Các ví dụ sau đây cho thấy các tệp mô-đun hoàn chỉnh cho một mô-đun ứng dụng và một mô-đun thư viện.

Mô-đun ứng dụng

Tệp app/lightbuild.yaml sau đây định cấu hình một mô-đun ứng dụng phụ thuộc vào mô-đun thư viện 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

Mô-đun thư viện

Tệp app-core/lightbuild.yaml sau đây định cấu hình một mô-đun thư viện sử dụng Jetpack Compose và Moshi, đồng thời chứa các kiểm thử cục bộ và kiểm thử đo lường:

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