- Использование Gradle
- Плагин и версии
- Поддержка JVM
- Поддержка JavaScript
- Поддержка Android
- Android Studio
- Настройка зависимостей
- Аннотации
- Пошаговая компиляция
- Поддержка Coroutines(сопрограммы)
- Названия модулей
- Поддержка кеша Gradle Build Cache (начиная с версии 1.2.20)
- Опции компилятора
- Атрибуты, общие для JVM, JS и JS DCE
- Атрибуты, общие для JVM и JS
- Атрибуты, специфичные для JVM
- Атрибуты, специфичные для JS
- Создание документации
- Примеры
- Kotlin DSL: Gradle scripts in Android made easy
- Let’s get started
- Is there anything left to do? 🤔
- AppConfig.kt:
- Versions.kt
- AppDependencies.kt
- settings.gradle
- settings.gradle.kts
- build.gradle
- build.gradle.kts
- Styling TextView using Kotlin DSL.
- Output:
Использование Gradle
Для сборки с помощью Gradle необходимо настроить kotlin-gradle плагин, применить его к своему проекту и добавить kotlin-stdlib зависимость. Эти действия могут быть сделаны автоматически с помощью IntelliJ IDEA во вкладке Tools | Kotlin | Configure Kotlin.
Плагин и версии
kotlin-gradle-plugin создает Kotlin ресурсы и модули.
Версия Kotlin обычно указывается в kotlin_version свойстве:
Это не требуется когда версия Kotlin Gradle плагина 1.1.1 и выше с Gradle plugins DSL.
Поддержка JVM
Чтобы настроить JVM необходимо использовать плагин Kotlin:
Начиная с Kotlin 1.1.1 плагин может быть применен автоматически с использованием Gradle plugins DSL:
version должен быть в данном блоке(как на примере), и не может быть использован из других скриптов сборки.
Kotlin ресурсы могут сочетаться с Java ресурсами из одной папки или разных папок. По умолчанию используются разные папки:
Соответствующее свойство sourceSets должно быть обновлено, если не использовано значение по умолчанию:
Поддержка JavaScript
Для использования JavaScript должен применяться другой плагин:
Данный плагин работает только для Kotlin файлов, таким образом рекомендуется хранить Kotlin и Java файлы раздельно (Это в случае если данный проект содержит Java файлы). Как и с поддержкой JVM, если не используются значения по умолчанию, необходимо определить папки ресурсов в sourceSets:
В дополнение к выходному файлу JavaScript плагин по умолчанию создает дополнительный JS-файл с двоичными дескрипторами. Эти файлы требуются в случае создании библиотеки, чтобы Kotlin модули могли наследоваться от нее, и должны распространяться вместе с библиотекой.
Процесс контролируется kotlinOptions.metaInfo свойством:
Поддержка Android
Android’s Gradle модель отличается от обычной Gradle модели, поэтому если необходимо собрать Android проект использующий Kotlin, необходимо применить kotlin-android плагин вместо kotlin:
Android Studio
При использовании Android Studio, необходимо добавить следующее под блоком android:
Это позводит Android Studio находить kotlin директорию в папке с ресурсами, поэтому, когда проект будет загружен в IDE, он будет правильно распознан. Другой способ — это добавить Kotlin классы в Java директорию, расположенную по пути src/main/java .
Настройка зависимостей
В дополнение к зависимостям kotlin-gradle-plugin , показанным выше, вам нужно добавить зависимость от стандартной библиотеки Kotlin:
Для поддержки JavaScript используйте compile «org.jetbrains.kotlin:kotlin-stdlib-js» .
Если вы собираетесь включить поддержку JDK 7 или JDK 8, вы можете использовать расширенную версию Kotlin standard library, которая содержит расширенный API, добавленный в новой JDK версии. Вместо kotlin-stdlib , используйте одну из следующих зависимостей:
В Kotlin 1.1.x, используйте kotlin-stdlib-jre7 вместо kotlin-stdlib-jre8 .
Если проект содержит Kotlin reflection или средства тестирования, вам также необходимо добавить соответствующие зависимости:
Начиная с Kotlin 1.1.2 зависимости из группы org.jetbrains.kotlin по умолчанию разрешены. Вы можете указать версию вручную, используя полную зависимость, например compile «org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version» .
Аннотации
Пошаговая компиляция
Kotlin поддерживает пошаговую компиляцию в Gradle. Пошаговая компиляция отслеживает изменения исходных файлов между сборками, поэтому будут скомпилированы только файлы, затронутые этими изменениями.
Начиная с Kotlin 1.1.1 пошаговая компиляция доступна по умолчанию.
Существует несколько способов переопределить настройку по умолчанию:
Добавить kotlin.incremental=true или kotlin.incremental=false либо в gradle.properties , либо в local.properties файл;
Добавить -Pkotlin.incremental=true или -Pkotlin.incremental=false как параметр командной строки. Обратите внимание, что в этом случае параметр должен быть добавлен к каждой последующей сборке, а любая сборка с отключенной пошаговой компиляцией делает недействительными пошаговые кеши.
Когда пошаговая компиляция включена, в журнале сборки должно появиться следующее сообщение:
Обратите внимание, что первая сборка не будет пошаговой.
Поддержка Coroutines(сопрограммы)
Coroutines добавлены как эксперементальная функция в Kotlin 1.2, поэтому компилятор Kotlin сообщает об использовании сопрограмм в вашем проекте. Чтобы отключить предупреждение, добавьте следующий блок в свой файл build.gradle :
Названия модулей
Модули Kotlin, создаваемые сборкой, называются соответственно свойству «archivesBaseName» в проекте. Если проект имеет широкое имя, например lib или jvm , что является общим для подпроектов, выходные файлы Kotlin, относящиеся к модулю ( * .kotlin_module ), могут столкнуться с модулями из сторонних модулей с тем же именем, это вызывает проблемы, когда проект упаковывается в один архив (например, APK).
Чтобы этого избежать, рассмотрите возможность установки уникального archivesBaseName вручную:
Поддержка кеша Gradle Build Cache (начиная с версии 1.2.20)
Kotlin плагин поддерживает Gradle Build Cache (Требуется версия 4.3 и выше; кеширование отключено в более низких версиях).
Задачи обработки аннотаций Kapt не кэшируются по умолчанию, поскольку обработчики аннотаций запускают произвольный код, который не обязательно преобразовывает входящие задачи в выходящие и может обращаться к файлам, которые не отслеживаются Gradle, и изменять их. Чтобы включить кэширование для kapt в любом случае, добавьте следующие строки в сценарий сборки:
Чтобы отключить кеширование для всех задач Kotlin, установите для параметра системного свойства kotlin.caching.enabled значение false (запустите сборку с аргументом -Dkotlin.caching.enabled=false ).
Опции компилятора
Чтобы указать дополнительные параметры компиляции используйте свойство kotlinOptions .
При поддержки JVM опции называются compileKotlin для релизного кода и compileTestKotlin для тестового кода. Задачи для настраиваемых исходных ресурсов вызываются по шаблону compile Kotlin .
Имена задач в проектах Android содержат build variant и следуют шаблону compile Kotlin , например, compileDebugKotlin , compileReleaseUnitTestKotlin .
При поддержки JavaScript задачи называются compileKotlin2Js и compileTestKotlin2Js соответственно, и compile Kotlin2Js для настраиваемых ресурсов.
Чтобы настроить задачу, используйте ее имя. Примеры:
Также возможно сконфигурировать все задачи компиляции Kotlin:
Ниже приведен полный список параметров для задач Gradle:
Атрибуты, общие для JVM, JS и JS DCE
Имя | Описание | Возможные значения | Значение по умолчанию |
---|---|---|---|
allWarningsAsErrors | Сообщить об ошибке если есть какие-либо предупреждения (warnings) | false | |
suppressWarnings | Не создавать предупреждения (warnings) | false | |
verbose | Включить подробный вывод журнала | false | |
freeCompilerArgs | Список дополнительных аргументов компилятора | [] |
Атрибуты, общие для JVM и JS
Имя | Описание | Возможные значения | Значение по умолчанию |
---|---|---|---|
apiVersion | Разрешить использование объявлений (declarations) только из указанных версий зависимых библиотек | «1.0», «1.1», «1.2», «1.3 (EXPERIMENTAL)» | |
languageVersion | Обеспечить совместимость источника с указанной языковой версией | «1.0», «1.1», «1.2», «1.3 (EXPERIMENTAL)» |
Атрибуты, специфичные для JVM
Имя | Описание | Возможные значения | Значение по умолчанию |
---|---|---|---|
javaParameters | Генерировать метаданные для reflection Java 1.8 по параметрам метода | false | |
jdkHome | Путь к домашнему каталогу JDK для включения в путь классов, если отличается от стандартного JAVA_HOME | ||
jvmTarget | Целевая версия сгенерированного байт-кода JVM (1.6 или 1.8), по умолчанию — 1.6 | «1.6», «1.8» | «1.6» |
noJdk | Не включать Java в classpath | false | |
noReflect | Не включайте реализацию Kotlin reflection в classpath | true | |
noStdlib | Не включать Kotlin runtime в classpath | true |
Атрибуты, специфичные для JS
Имя | Описание | Возможные значения | Значение по умолчанию |
---|---|---|---|
friendModulesDisabled | Отключить экспорт внутренних описаний (declaration) | false | |
main | Должна ли быть вызвана основная функция | «call», «noCall» | «call» |
metaInfo | Создание файлов .meta.js и .kjsm с метаданными. Использование их для создания библиотеки | true | |
moduleKind | Тип модуля, сгенерированного компилятором | «plain», «amd», «commonjs», «umd» | «plain» |
noStdlib | Не использовать Kotlin stdlib | true | |
outputFile | Выходной путь файла | ||
sourceMap | Создание источника (source map) | false | |
sourceMapEmbedSources | Вставлять исходные файлы (source map) в источник | «never», «always», «inlining» | |
sourceMapPrefix | Префикс для путей в источнике (source map) | ||
target | Создание JS-файлов для конкретной версии ECMA | «v5» | «v5» |
typedArrays | Перевести примитивные массивы на массивы в JS | true |
Создание документации
Чтобы создать документацию для проектов Kotlin, используйте Dokka; обратитесь к Dokka README для инструкций по настройке. Dokka поддерживает проекты на смешанном языке и может генерировать выходные данные в нескольких форматов, включая стандартный JavaDoc.
Для поддержки OSGi см. Страницу Kotlin OSGi.
Примеры
В следующих примерах показаны различные возможности настройки плагина Gradle:
Источник
Kotlin DSL: Gradle scripts in Android made easy
If you are scared of Gradle scripts with unfamiliar groovy syntax files, then Kotlin DSL is made for you. Its time to face the Gradle scripts with more confidence. In this article, we will convert some common Groovy-based Gradle scripts into Kotlin DSL scripts.
Let’s get started
Open half baked side android project 😉 of yours. In your project-level root folder create a folder named buildSrc same as that of your app/ folder in your project. This is a special folder to enable the Gradle scripts at the project level. Hit the sync button and you will see how these changes and adds some temporary files inside it.
Half the battle is done 😀 now in order to enable the Kotlin DSL we gotta do something more here. So put our lazy brain to work and create a file inside buildSrc naming it build.gradle.kts open now the newly created file to add some code that tells Gradle to enable the Kotlin-DSL plugin for our project.
Sync now, That’s it Battle is won, and Kotlin DSL is enabled in our project.
Is there anything left to do? 🤔
Yes, whatever we have done is of no use until we put Kotlin DSL into some action.
Kotlin DSL brings the simplicity of the Kotlin language syntax and rich API set right into the script files on top of that code completion makes it perfect to work with Gradle script files. We will use this to manage our dependencies and project settings configurations more elegantly. Kotlin DSL files have extension as .kts so we will be converting all of our .gradle files to .gradle.kts
Before converting our files to Kotlin DSL let’s have some necessary files in place in order to go ahead. Create folders inside the buildSrc folder as below and create the stated files.
AppConfig.kt:
This file helps us manage our app-level configurations related to the project at once place.
Versions.kt
This file helps us separate our versioning of the libraries in one place.
AppDependencies.kt
This file holds all the dependencies of our app related to UI, test, and other third-party libraries. Apart from that this also holds the Kotlin extension functions for implementation, testImplementation, androidTestImplementation, kapt which basically now accepts a list of String (dependencies) which is helpful for adding multiple dependencies at once instead of adding one by one in build.gradle file. You can play around and separate dependencies based on the module name also by creating a different list of dependencies for your module and add all at once by using a single line of code Gradle script.
Here is how it will look like when we are done adding all the Kotlin files.
Also, it’s no hard and fast rule we can also manage all these constants in one file also but if your project is large enough to make you go mad for a single change then it’s better to have separate the concerns in different files for different purposes. Let’s convert
settings.gradle
Our existing code for settings.gradle file as below
settings.gradle.kts
include is now just a function taking vararg of String to include the modules in the project. Moving next we gonna change our project level build.gradle file
build.gradle
build.gradle.kts
Kotlin DSL version is almost the same since it’s using DSL to map those syntaxes and tries to be as close as possible for example.
classpath is just a regular Kotlin function taking String as input. Which we all know and understand and can relate the syntax. Let’s see how our main app-level build.gradle file changes to build.gradle.kts
Plugins are the first thing in the main app-level Gradle file which enables the android support in regular Intellij project or Kotlin support in an android project or any third party plugin which needed at module level can be applied in this file, we will see show that changes
will be changed to
or you can use another way of adding plugins as shown below, the above one is the DSL way of doing things.
now let’s try to go chunk by chunk for an android block with the basic setup.
will be changed to
Now it’s possible to directly access the Kotlin object constants or any other constants like as shown above. Here we are using the earlier created constants in file AppConfig for the app level configurations. Next, let’s see how we can create the debug and release versions.
will be changed to
you don’t have to create debug because it’s there by default until unless needed to change some properties. If so then do something like this.
coming to the main dependencies this is how it was like before
will be now changed to below
this is quite maintainable, easy to read & understand.
putting all this together will look like as below.
If you have any android module, conversion goes almost the same for the modules as well instead of using an android id plugin use library plugin id.
Kotlin DSL is not limited to the usages across Gradle scripts it’s way broader than just scripting. Let’s go and explore this side of Kotlin DSL by putting this into implementation.
Styling TextView using Kotlin DSL.
Let’s start by creating the backbone which will support the DSL.
in our MainActivity we will use this as follow.
Output:
This is the very basic example of Kotlin DSL, we can write to express almost anything using this. This is a much more clean and expressive way of doing programming. Since it uses Kotlin lambda expressions extensively to achieve this, we should be conscious of the extra classes it generates at the byte code level. So how to fix this 🤔, simply try to inline the lambda expressions where ever possible in order to reduce the extra class which would get generated for the small code blocks.
That’s it folks for today. Please be generous enough to comment for feedback or suggestions or any queries. Thanks for reading 😊.
Источник