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:

Cài đặt Mô tả
project.name Tên dự án, ví dụ: MyApp. Android Studio hiển thị tên này làm thư mục gốc của cửa sổ Project (Dự án). Giống như rootProject.name trong Kotlin DSL, tên này tách biệt với tên ứng dụng và mã ứng dụng của bạn.
modules Các mô-đun trong dự án, chẳng hạn như mô-đun ứng dụng (app) và mô-đun thư viện (app-core).
repositories Kho lưu trữ từ xa mà Lightbuild phân giải các phần phụ thuộc. Để biết thông tin chi tiết, hãy xem phần Kho lưu trữ.
lightbuild.version Phiên bản Lightbuild mà dự án sử dụng.
build.kotlin.version Phiên bản Kotlin mà dự án sử dụng.
build.java.version Phiên bản trình biên dịch Java mà dự án yêu cầu.
build.jvmTarget Phiên bản mục tiêu của mã byte JVM được tạo.

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:

Cài đặt Mô tả
name Tên cho kho lưu trữ.
url URL của kho lưu trữ.
credentials Không bắt buộc. Các khoá liên kết với tên người dùng và mật khẩu của kho lưu trữ trong tệp local.properties. Để biết thông tin chi tiết, hãy xem phần Thông tin xác thực kho lưu trữ.

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 Mô tả
platform Nền tảng mà mô-đun nhắm đến: android.
type Loại mô-đun: application cho mô-đun ứng dụng hoặc library cho mô-đun thư viện. Để biết thêm thông tin, hãy xem bài viết Cấu trúc dự án Lightbuild.
optionalFeatures Các tính năng không bắt buộc cần bật cho mô-đun, chẳng hạn như com.android.tools.lightbuild.protobuf để hỗ trợ Vùng đệm giao thức. Để biết thông tin chi tiết, hãy xem phần Vùng đệm giao thức.
android Chế độ cài đặt Android của mô-đun. Để biết thông tin chi tiết, hãy xem phần Cài đặt Android.

Cài đặt Android

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

Cài đặt Mô tả
namespace Không gian tên của mô-đun. Để biết thêm thông tin, hãy xem phần Đặt không gian tên.
compileSdk Cấp độ API mà mô-đun biên dịch. Để biết thông tin chi tiết, hãy xem phần Phiên bản SDK.
minSdk Cấp độ API tối thiểu mà mô-đun hỗ trợ.
targetSdk Cấp độ API mà ứng dụng nhắm đến. Chỉ được hỗ trợ trong các mô-đun ứng dụng.
applicationId Mã ứng dụng của ứng dụng. Đặt trong mô-đun ứng dụng.
versionCode Mã phiên bản của ứng dụng. Đặt trong mô-đun ứng dụng.
versionName Tên phiên bản của ứng dụng. Đặt trong mô-đun ứng dụng.
packaging Chế độ cài đặt để đóng gói bản dựng debug và release của ứng dụng, chẳng hạn như ký bản phát hành. Chỉ được hỗ trợ trong mô-đun ứng dụng. Để biết thông tin chi tiết, hãy xem phần Đóng gói.
dependencies Phần phụ thuộc của mô-đun vào các mô-đun khác và vào thư viện bên ngoài. Để biết thông tin chi tiết, hãy xem phần Phần phụ thuộc.
kspProcessors Trình xử lý KSP tạo mã cho mô-đun. Để biết thông tin chi tiết, hãy xem phần Bộ xử lý KSP.
tests Kiểm thử cục bộ và kiểm thử đo lường của mô-đun. Để biết thông tin chi tiết, hãy xem phần Thử nghiệm.

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