Lightbuild 구성 참조

실험용: Lightbuild는 실험용 프리뷰입니다. 설계는 아직 개발 중이며 아직 모든 Android 빌드 기능을 지원하지는 않습니다. 프로덕션 앱, 기존 프로젝트 또는 야심 찬 새 앱의 경우 Kotlin DSL을 계속 사용하세요. Lightbuild 프리뷰는 소규모 앱, 프로토타입, 데모에 가장 적합합니다. 지원되는 기능에 관한 자세한 내용은 Kotlin DSL 비교 및 출시 노트를 참고하세요.

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 스튜디오는 이 이름을 Project 창의 루트로 표시합니다. Kotlin DSL의 rootProject.name와 마찬가지로 앱 이름 및 애플리케이션 ID와는 별개입니다.
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

주의: local.properties 파일에는 민감한 사용자 인증 정보가 포함되어 있으므로 버전 제어에 추가하지 마세요.

모듈 파일

각 모듈의 디렉터리에는 모듈의 설정을 정의하는 lightbuild.yaml 파일이 있습니다. 다음 표에서는 최상위 설정을 설명합니다.

설정	설명
platform	모듈이 타겟팅하는 플랫폼: android
type	모듈 유형: 앱 모듈의 경우 application, 라이브러리 모듈의 경우 library 자세한 내용은 Lightbuild 프로젝트 구조를 참고하세요.
optionalFeatures	모듈에 사용 설정할 선택적 기능입니다(예: 프로토콜 버퍼 지원을 위한 com.android.tools.lightbuild.protobuf). 자세한 내용은 프로토콜 버퍼를 참고하세요.
android	모듈의 Android 설정입니다. 자세한 내용은 Android 설정을 참고하세요.

Android 설정

android 블록에는 모듈의 Android 빌드 설정이 포함됩니다.

설정	설명
namespace	모듈의 네임스페이스입니다. 자세한 내용은 네임스페이스 설정을 참고하세요.
compileSdk	모듈이 컴파일되는 API 수준입니다. 자세한 내용은 SDK 버전을 참고하세요.
minSdk	모듈에서 지원하는 최소 API 수준입니다.
targetSdk	앱이 타겟팅하는 API 수준입니다. 앱 모듈에서만 지원됩니다.
applicationId	앱의 애플리케이션 ID입니다. 앱 모듈에서 설정합니다.
versionCode	앱의 버전 코드입니다. 앱 모듈에서 설정합니다.
versionName	앱의 버전 이름입니다. 앱 모듈에서 설정합니다.
packaging	출시 서명과 같은 앱의 debug 및 release 빌드 패키징 설정 앱 모듈에서만 지원됩니다. 자세한 내용은 패키징을 참고하세요.
dependencies	다른 모듈 및 외부 라이브러리에 대한 모듈의 종속 항목입니다. 자세한 내용은 종속 항목을 참고하세요.
kspProcessors	모듈의 코드를 생성하는 KSP 프로세서입니다. 자세한 내용은 KSP 프로세서를 참고하세요.
tests	모듈의 로컬 및 계측 테스트 자세한 내용은 테스트를 참고하세요.

SDK 버전

compileSdk, minSdk, targetSdk 설정을 version.release.apiLevel 아래의 API 수준으로 지정합니다. 예를 들어 다음 설정은 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: 외부 라이브러리이며 group:artifact:version 형식의 Maven 좌표로 작성됩니다.

예를 들어 다음 설정은 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 주석 라이브러리는 이 모듈을 컴파일하는 데만 사용됩니다. Core KTX는 기본 설정을 사용합니다.

compile 설정은 종속 항목에 대해 컴파일되는 모듈을 제어합니다.

• private (기본값): 이 모듈은 종속 항목에 대해 컴파일되지만 이 모듈에 종속되는 모듈은 컴파일되지 않습니다.
• public: 이 모듈과 이 모듈에 종속된 모듈은 종속 항목에 대해 컴파일됩니다. 모듈의 공개 API가 종속 항목의 유형을 사용하는 경우 public를 사용합니다.
• off: 이 모듈은 종속 항목에 대해 컴파일되지 않습니다.

runtime 설정은 런타임에 종속 항목을 사용할 수 있는지 여부를 제어합니다.

• public (기본값): 종속 항목은 런타임에 이 모듈과 이 모듈에 종속된 모듈에서 사용할 수 있습니다.
• off: 런타임에 종속 항목을 사용할 수 없습니다. 주석과 같이 컴파일 시간에만 코드에 필요한 종속 항목에는 off를 사용합니다.

compile 및 runtime은 둘 다 off일 수 없습니다. 테스트 종속 항목에서 compile은 private 또는 off만 될 수 있습니다.

이러한 설정이 api 및 compileOnly와 같은 Kotlin DSL 구성과 어떻게 일치하는지 확인하려면 Lightbuild와 Kotlin DSL 비교를 참고하세요.

KSP 프로세서

Moshi 또는 Room과 같은 Kotlin Symbol Processing (KSP) 기반 코드 생성기를 사용하려면 프로세서를 kspProcessors 블록에 추가하고 런타임에 코드에서 사용하는 라이브러리를 dependencies 블록에 추가합니다. Lightbuild는 빌드 중에 KSP 플러그인을 자동으로 적용하고 코드 생성을 구성합니다.

예를 들어 다음 설정은 KSP 코드 생성기로 Moshi를 구성합니다.

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

참고: kspProcessors 블록은 외부 Maven 종속 항목만 지원합니다. KSP 프로세서에는 로컬 모듈 종속 항목이 지원되지 않습니다.

프로토콜 버퍼

라이브러리 모듈의 프로토콜 버퍼 (.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는 Android에 권장되는 프로토콜 버퍼 라이트 런타임용 자바 및 Kotlin 클래스를 생성합니다.

테스트

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 빌드를 구성합니다. 자체 키로 출시 빌드에 서명하려면 release 프로필에 signing 블록을 추가합니다.

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를 직접 작성하거나 환경 변수를 참조할 수도 있습니다. 빌드 시 Lightbuild는 각 참조를 환경 변수의 값으로 바꿉니다. 각 값에는 참조만 포함되어야 합니다. Lightbuild는 더 긴 값의 일부인 참조(예: ${HOME}/upload-keystore.jks)를 대체하지 않습니다.

중요: 민감한 정보가 노출되지 않도록 하려면 lightbuild.yaml 파일에 비밀번호를 직접 작성하거나 키 저장소를 버전 제어에 체크인하지 마세요.

경고: signing 블록에서 참조하는 환경 변수가 설정되지 않으면 디버그 빌드를 포함한 앱 모듈의 모든 빌드가 실패합니다.

예

다음 예는 앱 모듈과 라이브러리 모듈의 전체 모듈 파일을 보여줍니다.

앱 모듈

다음 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