├── README.md ├── Migrate_Groovy_to_Kotlin.md └── Gradle_Kotlin_DSL_Primer.md /README.md: -------------------------------------------------------------------------------- 1 | # kotlin-dsl-kr 2 | kotlin dsl 공식 문서의 비공식 한국어 번역입니다. 3 | 4 | - [Gradle 코틀린 DSL 입문서](./Gradle_Kotlin_DSL_Primer.md) 5 | - [빌드스크립트를 Groovy에서 Kotlin으로 변경하기](./Migrate_Groovy_to_Kotlin.md) 6 | -------------------------------------------------------------------------------- /Migrate_Groovy_to_Kotlin.md: -------------------------------------------------------------------------------- 1 | [원문](https://guides.gradle.org/migrating-build-logic-from-groovy-to-kotlin/) 2 | 3 | ## 빌드스크립트를 Groovy에서 Kotlin으로 변경하기 4 | 5 | ### 목차 6 | - 변경하기전 확인사항 7 | - Groovy 스크립트 준비 8 | - 파일 이름짓기 9 | - 플러그인 적용 10 | - 플러그인 설정 11 | - 비권장 설정사항 12 | - 작업(tasks) 설정 13 | - 작업(tasks) 생성 14 | - 설정과 의존성 15 | - 정책 마이그레이션 16 | - Groovy와 Kotlin 함께 사용(상호운용성) 17 | - 요약 18 | - 피드백 19 | -------------------------------------------------------------------------------- /Gradle_Kotlin_DSL_Primer.md: -------------------------------------------------------------------------------- 1 | [원문](https://docs.gradle.org/5.0/userguide/kotlin_dsl.html) 2 | 3 | # Gradle 코틀린 DSL 입문서 4 | ### 목차 5 | - [전제조건](#전제조건) 6 | - [IDE 지원사항](#IDE-지원사항) 7 | - [코틀린 DSL 스크립트](#코틀린-DSL-스크립트) 8 | - [Type-safe한 모델 접근자](Type-safe한-모델-접근자) 9 | - Multi-Project에서 빌드하기 10 | - `plugins {}` 를 사용할수 없을때 11 | - container 객체와 사용하기 12 | - 런타임 속성(properties)과 사용하기 13 | - 코틀린 DSL 플러그인 14 | - 내장(embedded) 코틀린 코드 15 | - 그루비와 코틀린 함께 사용하기(상호운용성) 16 | - 한계 17 | 18 | Gradle의 코틀린 DSL은 이전에 사용되오던 Groovy DSL을 대체할 수 있는 여러 구문들을 제공합니다. 19 | 이를 통해 여러 IDE들의 내용완성(content assist), 리팩토링, 문서화 등을 제공받을 수 있습니다. 20 | 이 문서에서는 코틀린 DSL의 주요 작성법과 Gradle API의 사용법에 대해 다룹니다. 21 | 22 | > Note : 이미 만들어놓은 Gradle를 코틀린 DSL로 마이그레이션하는데 관심이 있는경우 [마이그레이션 가이드](.)를 읽어보세요 23 | 24 | ### 전제조건 25 | - 내장(embedded) 코틀린 컴파일러는 리눅스, 맥OS, 윈도우, Cygwin, FreeBSD와 x86-64 기반 Solaris 에서 동작합니다. 26 | - 코틀린 문법과 기본 기능들은 본 문서를 이해하는데 많은 도움이 됩니다. [코틀린 레퍼런스 문서](https://kotlinlang.org/docs/reference/) 나 [Kotlin Tutorial](https://kotlinlang.org/docs/tutorials/koans.html) 문서를 참고하세요. 27 | - `plugin {}` 블록을 사용하면 여러 IDE 지원을 받을수 있으니 추천드립니다. 28 | 29 | ### IDE 지원사항 30 | IntelliJ와 Android Studio는 완전하게 Kotlin DSL을 지원합니다. 다른 IDE들은 아직은 완벽하게 지원하진 않으나, 사용할 수는 있습니다. 31 | 32 | | | Build import | Syntax highlighting | Semantic editor | 33 | |--------:|:--------:|:--------:|:--------:| 34 | | IntelliJ IDEA | :white_check_mark: | :white_check_mark: | :white_check_mark: | 35 | | Android Studio | :white_check_mark: | :white_check_mark: | :white_check_mark: | 36 | | Eclipse | :white_check_mark: | :white_check_mark: | :x: | 37 | | CLion | :white_check_mark: | :white_check_mark: | :x: | 38 | | Apache Netbeans | :white_check_mark: | :white_check_mark: | :x: | 39 | | Visual Studio Code(LSP) | :white_check_mark: | :white_check_mark: | :x: | 40 | | Visual Studio | :white_check_mark: | :x: | :x: | 41 | 42 | * Syntax highlighting : Gradle 코틀린 DSL 코드에서 문법별 코드 색상화 43 | * Semantic editor : 코드 자동완성, 코드내에서 이동, 문서화, 리팩토링 등 44 | 45 | 아래 한계에서 언급되듯이, Gradle 모델에서 프로젝트를 가져와야 위 도구들이 지원됩니다. 46 | 47 | 추가적으로, IntelliJ 와 Android Studio는 편집을 할때 최대 3개의 Gradle 데몬이 동작될 수 있습니다. (빌드, 설정파일, 초기화 스크립트) 48 | 설정이 느리게 되어있다면 IDE 반응성에 영향을 줄 수 있습니다. 그럴경우 [성능향상가이드](https://guides.gradle.org/performance/#configuration) 를 확인해주세요. 49 | 50 | #### 자동 import vs 자동 의존성 추가 51 | IntelliJ와 그에서 파생된 Android Studio 둘 다 빌드 로직의 변경을 감지해 두가지 옵션을 제공합니다. 52 | 1. 모든 변경사항 다시 불러오기 53 | ![intellij-build-import-popup](https://docs.gradle.org/5.0/userguide/img/intellij-build-import-popup.png) 54 | 2. 스크립트를 변경할 때마다 의존성 불러오기 55 | ![intellij-script-dependencies-reload](https://docs.gradle.org/5.0/userguide/img/intellij-script-dependencies-reload.png) 56 | 57 | 1번은 비활성화하고 2번은 활성화하는것을 권장합니다. 그렇게하면 스크립트를 편집하는동안 피드백을 빠르게 받을 수 있고, 전체 빌드가 되는 시점을 제어할 수 있습니다. 58 | 59 | > 역자 : 1번 방식은 상대적으로 오래걸리기에, 수동으로 시점을 제어하는걸 권장하는거라고 생각합니다. 60 | 61 | #### 문제 해결하기 62 | IDE 지원은 아래 두 모듈을 통해 제공됩니다. 63 | - IntelliJ/Android Studio를 통해 사용되는 kotlin plugin 64 | - Gradle 65 | 66 | 지원되는 내용은 각 버전에 따라 다릅니다. 67 | 68 | 문제가 발생했다면, 제일먼저 커맨드에서 `./gradlew tasks` 를 실행해 IDE 문제인지 Gradle 문제인지 부터 확인해 보세요. 69 | 커맨드에서 동일한 문제가 발생한다면 그것은 IDE문제가 아닌 빌드의 문제입니다. 70 | 71 | 커맨드에선 빌드가 잘 된다면, IDE의 캐시를 지우고 다시 실행해보세요. 72 | 73 | 위 시도를 해도 동작하지 않아, IDE의 문제가 있다고 생각되면 다음을 시도해 볼 수 있습니다. 74 | - `./gradlew tasks` 에서 더 자세한 정보 살펴보기 75 | - 아래 경로에 존재하는 로그를 확인해보기 76 | - `$HOME/Library/Logs/gradle-kotlin-dsl` (맥 OS X 기준) 77 | - `$HOME/.gradle-kotlin-dsl/logs` (리눅스 기준) 78 | - `$HOME/Application Data/gradle-kotlin-dsl/log` (윈도우 기준) 79 | - [Kotlin Issue Tracker](https://github.com/gradle/kotlin-dsl/issues/)에 이슈남기기 80 | 81 | IDE 문제일 경우 해당 이슈 트래커에 문의해주세요 82 | - [JetBrain IDEA](https://docs.gradle.org/5.0/userguide/kotlin_dsl.html) 83 | - [Google Android Studio](https://docs.gradle.org/5.0/userguide/kotlin_dsl.html) 84 | 85 | ### 코틀린 DSL 스크립트 86 | Groovy 기반의 환경에서 처럼, Kotlin DSL도 Gradle의 Java API를 통해 구현됩니다. 87 | Kotlin DSL의 모든 코틀린 코드들은 Gradle을 통해 컴파일되고 실행됩니다. 88 | 객체, 함수, 속성들은 Gradle API 와 추가된 플러그인들을 통해 사용됩니다. 89 | 90 | #### 스크립트 파일 네이밍 91 | - Groovy DSL은 `.gradle` 확장자를 사용합니다. 92 | - Kotlin DSL은 `.gradle.kts` 확장자를 사용합니다. 93 | 94 | Kotlin DSL을 활성화하려면, `.gradle` 확장자를 `.gradle.kts` 로 바꾸세요. 그리고 설정 및 초기화 파일에도 적용하면 됩니다. 95 | Groovy DSL 스크립트와 Kotlin DSL 스크립트를 섞어서 사용할 수 있다는걸 기억하세요. 96 | 97 | IDE의 원활한 지원을 위해 아래 규칙을 따르는걸 권장합니다. 98 | - 설정 스크립트(혹은 `Settings` 객체와 관련된 스크립트)는 `*.settings.gradle.kts` 패턴으로 하세요. 99 | - 초기화(initialization) 스크립트는 `*.init.gradle.kts` 혹은 `init.gradle.kts` 패턴으로 하세요. 100 | 101 | 이는 스크립트가 어떤 타입인지 IDE가 알게 하기 위함입니다. 102 | 103 | #### 내장(implicit) import 104 | 모든 Kotlin DSL 스크립트는 다음과 같은 내장 import 문이 있습니다. 105 | 106 | - [Gradle 기본 API](https://docs.gradle.org/5.0/userguide/writing_build_scripts.html#script-default-imports) 107 | - `org.gradle.kotlin.dsl` 와 `org.gradle.kotlin.dsl.plugins.dsl` 패키지의 kotlin DSL api 108 | 109 | > Note **내부 Kotlin DSL Api를 사용하는걸 지양하세요** 110 | > 내부 Kotlin DSL Api를 사용하면 Gradle이나 plugin이 변경될때 빌드가 깨질 가능성이 있습니다. 111 | > 역자 : 내부 함수에 대해선 상위/하위호환을 고려하지 않고있어 그런것 같습니다. 112 | 113 | ### Type-safe한 모델 접근자 114 | Groovy DSL에선 런타임에 정의된 요소또한 참조할 수 있었습니다. 이름설정이나 `SourceSe`, `implementation`등을 그렇게 사용해왔었습니다. 115 | 116 | Kotlin DSL은 이런 동적인 요소들을 플러그인을 통해 type-safe한 모델로 변경합니다. 117 | 118 | #### 어떻게 Type-safe할까? 119 | Kotlin DSL은 아래 항목들을 플러그인을 통해 type-safe한 접근자를 사용하도록 지원합니다. 120 | 121 | - 의존성과 사용자 지정 설정(`implementation` 이나 `runtimeOnly` 같은 Java Plugin 기반 설정) 122 | - 프로젝트 확장기능과 문법들(`sourceSets` 등) 123 | - `tasks`와 `configuration` 내 요소들 124 | - 프로젝트 확장 container 내 요소들 125 | - 위에 나와있는 각각의 확장요소들 126 | 127 | > Note : 메인 빌드 스크립트만 Type-safe 접근자를 가집니다. 초기화(Initialization), 설정, 플러그인 스크립트는 지원되지 않습니다. 이 한계는 나중에 수정 될 예정입니다. 128 | 129 | Type-safe 모델 접근자의 사용가능여부는 스크립트 본문이 실행되기 직전 `plugin {}` 다음에 계산됩니다. 130 | 그렇기 때문에 스크립트 본문이 실행된 이후에 제공된 모델들에 대해선 Type-safe 접근자가 동작하지 않습니다. 131 | 예를 들어, 빌드스크립트에 선언한 설정들이 그렇습니다. 하지만 이 방식은 Parent 프로젝트에 적용된 플러그인에서 제공되는 모델들에 대해 Type-safe 하다는걸 의미합니다. 132 | 아래 프로젝트는 type-safe 접근자를 사용해 설정, 확장, 객체를 어떻게 접근하는지를 다룹니다. 133 | 134 | 예제1. Type-safe 접근자 사용하기 135 | ```kotlin 136 | // build.gradle.kts 137 | 138 | plugins { 139 | `java-library` 140 | } 141 | 142 | dependencies { (1) 143 | api("junit:junit:4.12") 144 | implementation("junit:junit:4.12") 145 | testImplementation("junit:junit:4.12") 146 | } 147 | 148 | configurations { (1) 149 | implementation { 150 | resolutionStrategy.failOnVersionConflict() 151 | } 152 | } 153 | 154 | sourceSets { (2) 155 | main { (3) 156 | java.srcDir("src/core/java") 157 | } 158 | } 159 | 160 | java { (4) 161 | sourceCompatibility = JavaVersion.VERSION_11 162 | targetCompatibility = JavaVersion.VERSION_11 163 | } 164 | 165 | tasks { 166 | test { (5) 167 | testLogging.showExceptions = true 168 | } 169 | } 170 | 171 | ``` 172 | 173 | 1. `Java Library Plugin` 으로부터 `api`, `implementation`, `testImplementation` 등 함수를 접근 할 수 있습니다. 174 | 2. 프로젝트 확장(extension) 함수를 통해 `sourceSets` 함수를 접근 할 수 있습니다. 175 | 3. `main` 함수를 접근 할 수 있습니다. 176 | 4. `main` sourceSets의 확장으로 `java` 함수를 접근 할 수 있습니다. 177 | 5. `test` 함수를 접근 할 수 있습니다. 178 | 179 | > Note : 180 | --------------------------------------------------------------------------------