Начало работы с пользовательскими скриптами Kotlin — руководство

Структура проекта

Минимальный проект пользовательских скриптов Kotlin состоит из двух частей:

• Определение скрипта — набор параметров и конфигураций, определяющих, как скрипты этого типа распознаются, обрабатываются, компилируются и выполняются.

• Среда выполнения скриптов — приложение или компонент, который обрабатывает компиляцию и выполнение скриптов, то есть фактически запускает скрипты этого типа.

Учитывая это, лучше разделить проект на два модуля.

Перед началом работы

Скачайте и установите последнюю версию IntelliJ IDEA.

Создание проекта

1. В IntelliJ IDEA выберите Файл | Создать | Проект.

2. На панели слева выберите Новый проект.

3. Укажите имя нового проекта и при необходимости измените его расположение.

4. В списке Язык выберите Kotlin.

5. Выберите систему сборки Gradle.

6. В списке JDK выберите JDK, который хотите использовать в проекте.

   • Если JDK установлен на компьютере, но не указан в IDE, выберите Добавить JDK и укажите путь к домашнему каталогу JDK.

   • Если на компьютере нет нужного JDK, выберите Скачать JDK.

7. Для параметра Gradle DSL выберите язык Kotlin или Gradle.

8. Нажмите Создать.

Добавление модулей скриптинга

Теперь у вас есть пустой проект Kotlin/JVM Gradle. Добавьте необходимые модули: определение скрипта и среду выполнения скриптов.

1. В IntelliJ IDEA выберите Файл | Создать | Модуль.

2. На панели слева выберите Новый модуль. Этот модуль будет содержать определение скрипта.

3. Укажите имя нового модуля и при необходимости измените его расположение.

4. В списке Язык выберите Java.

5. Выберите систему сборки Gradle и Kotlin для параметра Gradle DSL, если хотите писать скрипт сборки на Kotlin.

6. В качестве родительского модуля выберите корневой модуль.

7. Нажмите Создать.

   

8. В файле build.gradle(.kts) модуля удалите version плагина Kotlin Gradle. Он уже указан в скрипте сборки корневого проекта.

9. Повторите предыдущие шаги, чтобы создать модуль для среды выполнения скриптов.

Структура проекта должна выглядеть следующим образом:

Пример такого проекта и другие примеры скриптинга Kotlin можно найти в репозитории kotlin-script-examples на GitHub.

Создание определения скрипта

Сначала определите тип скрипта: что разработчики смогут писать в скриптах этого типа и как эти скрипты будут обрабатываться. В этом руководстве это включает поддержку аннотаций @Repository и @DependsOn в скриптах.

1. В модуле определения скрипта добавьте зависимости от компонентов скриптинга Kotlin в блок dependencies файла build.gradle(.kts). Эти зависимости предоставляют API, необходимые для определения скрипта:

   dependencies {
       implementation("org.jetbrains.kotlin:kotlin-scripting-common")
       implementation("org.jetbrains.kotlin:kotlin-scripting-jvm")
       implementation("org.jetbrains.kotlin:kotlin-scripting-dependencies")
       implementation("org.jetbrains.kotlin:kotlin-scripting-dependencies-maven")
       // coroutines dependency is required for this particular definition
       implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0") 
   }
   

   dependencies {
       implementation 'org.jetbrains.kotlin:kotlin-scripting-common'
       implementation 'org.jetbrains.kotlin:kotlin-scripting-jvm'
       implementation 'org.jetbrains.kotlin:kotlin-scripting-dependencies'
       implementation 'org.jetbrains.kotlin:kotlin-scripting-dependencies-maven'
       // coroutines dependency is required for this particular definition
       implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.11.0'
   }
   

2. Создайте в модуле каталог src/main/kotlin/ и добавьте файл исходного кода Kotlin, например scriptDef.kt.

3. В файле scriptDef.kt создайте класс. Он будет суперклассом для скриптов этого типа, поэтому объявите его как abstract или open.

   // abstract (or open) superclass for scripts of this type
   abstract class ScriptWithMavenDeps
   

   Позже этот класс также будет использоваться как ссылка на определение скрипта.

4. Чтобы сделать класс определением скрипта, пометьте его аннотацией @KotlinScript. Передайте аннотации два параметра:

   • fileExtension — строка, заканчивающаяся на .kts, которая задаёт расширение файлов для скриптов этого типа.

   • compilationConfiguration — класс Kotlin, наследующий ScriptCompilationConfiguration и задающий особенности компиляции для этого определения скрипта. Вы создадите его на следующем шаге.

    // @KotlinScript annotation marks a script definition class
    @KotlinScript(
        // File extension for the script type
        fileExtension = "scriptwithdeps.kts",
        // Compilation configuration for the script type
        compilationConfiguration = ScriptWithMavenDepsConfiguration::class
    )
    abstract class ScriptWithMavenDeps
   
    object ScriptWithMavenDepsConfiguration: ScriptCompilationConfiguration()
   

5. Задайте конфигурацию компиляции скрипта, как показано ниже.

    object ScriptWithMavenDepsConfiguration : ScriptCompilationConfiguration(
        {
            // Implicit imports for all scripts of this type
            defaultImports(DependsOn::class, Repository::class)
            jvm {
                // Extract the whole classpath from context classloader and use it as dependencies
                dependenciesFromCurrentContext(wholeClasspath = true) 
            }
            // Callbacks
            refineConfiguration {
                // Process specified annotations with the provided handler
                onAnnotations(DependsOn::class, Repository::class, handler = ::configureMavenDepsOnAnnotations)
            }
        }
    )
   

   Функция configureMavenDepsOnAnnotations выглядит следующим образом:

    // Handler that reconfigures the compilation on the fly
    fun configureMavenDepsOnAnnotations(context: ScriptConfigurationRefinementContext): ResultWithDiagnostics<ScriptCompilationConfiguration> {
        val annotations = context.collectedData?.get(ScriptCollectedData.collectedAnnotations)?.takeIf { it.isNotEmpty() }
            ?: return context.compilationConfiguration.asSuccess()
        return runBlocking {
            resolver.resolveFromScriptSourceAnnotations(annotations)
        }.onSuccess {
            context.compilationConfiguration.with { 
                dependencies.append(JvmDependency(it))
            }.asSuccess()
        }
    }
   
    private val resolver = CompoundDependenciesResolver(FileSystemDependenciesResolver(), MavenDependenciesResolver())
   

   Полный код можно найти здесь.

Создание среды выполнения скриптов

Следующий шаг — создать среду выполнения скриптов, компонент, который обрабатывает выполнение скриптов.

1. В модуле среды выполнения скриптов добавьте зависимости в блок dependencies файла build.gradle(.kts):

   • Компоненты скриптинга Kotlin, предоставляющие API, необходимые для среды выполнения скриптов

   • Созданный ранее модуль определения скрипта

   dependencies {
       implementation("org.jetbrains.kotlin:kotlin-scripting-common")
       implementation("org.jetbrains.kotlin:kotlin-scripting-jvm")
       implementation("org.jetbrains.kotlin:kotlin-scripting-jvm-host")
       implementation(project(":script-definition")) // the script definition module
   }
   

   dependencies {
       implementation 'org.jetbrains.kotlin:kotlin-scripting-common'
       implementation 'org.jetbrains.kotlin:kotlin-scripting-jvm'
       implementation 'org.jetbrains.kotlin:kotlin-scripting-jvm-host'
       implementation project(':script-definition') // the script definition module
   }
   

2. Создайте в модуле каталог src/main/kotlin/ и добавьте файл исходного кода Kotlin, например host.kt.

3. Определите функцию main для приложения. В её теле проверьте, что ей передан один аргумент — путь к файлу скрипта, — и выполните скрипт. Выполнение скрипта будет задано в отдельной функции evalFile на следующем шаге. Пока оставьте её пустой.

   Функция main может выглядеть так:

    fun main(vararg args: String) {
        if (args.size != 1) {
            println("usage: <app> <script file>")
        } else {
            val scriptFile = File(args[0])
            println("Executing script $scriptFile")
            evalFile(scriptFile)
        }
    }
   

4. Определите функцию вычисления скрипта. В ней будет использоваться определение скрипта. Получите его, вызвав createJvmCompilationConfigurationFromTemplate и указав класс определения скрипта в качестве параметра типа. Затем вызовите BasicJvmScriptingHost().eval, передав ей код скрипта и конфигурацию его компиляции. Функция eval возвращает экземпляр ResultWithDiagnostics, поэтому укажите этот тип в качестве возвращаемого типа функции.

    fun evalFile(scriptFile: File): ResultWithDiagnostics<EvaluationResult> {
        val compilationConfiguration = createJvmCompilationConfigurationFromTemplate<ScriptWithMavenDeps>()
        return BasicJvmScriptingHost().eval(scriptFile.toScriptSource(), compilationConfiguration, null)
    }
   

5. Измените функцию main, чтобы она выводила информацию о выполнении скрипта:

    fun main(vararg args: String) {
        if (args.size != 1) {
            println("usage: <app> <script file>")
        } else {
            val scriptFile = File(args[0])
            println("Executing script $scriptFile")
            val res = evalFile(scriptFile)
            res.reports.forEach {
                if (it.severity > ScriptDiagnostic.Severity.DEBUG) {
                    println(" : ${it.message}" + if (it.exception == null) "" else ": ${it.exception}")
                }
            }
        }
    }
   

Полный код можно найти здесь

Запуск скриптов

Чтобы проверить работу среды выполнения скриптов, подготовьте скрипт для выполнения и конфигурацию запуска.

1. Создайте в корневом каталоге проекта файл html.scriptwithdeps.kts со следующим содержимым:

   @file:Repository("https://maven.pkg.jetbrains.space/public/p/kotlinx-html/maven")
   @file:DependsOn("org.jetbrains.kotlinx:kotlinx-html-jvm:0.7.3")
   
   import kotlinx.html.*; import kotlinx.html.stream.*; import kotlinx.html.attributes.*
   
   val addressee = "World"
   
   print(
       createHTML().html {
           body {
               h1 { +"Hello, $addressee!" }
           }
       }
   )
   

   В нём используются функции из библиотеки kotlinx-html-jvm, указанной в аргументе аннотации @DependsOn.

2. Создайте конфигурацию запуска, которая запускает среду выполнения скриптов и выполняет этот файл:

   1. Откройте host.kt и найдите функцию main. Слева от неё есть значок Запуск на полях редактора.

   2. Щёлкните правой кнопкой мыши по значку на полях редактора и выберите Изменить конфигурацию запуска.

   3. В диалоговом окне Создание конфигурации запуска добавьте имя файла скрипта в поле Аргументы программы и нажмите ОК.

      

3. Запустите созданную конфигурацию.

Вы увидите, как выполняется скрипт: разрешается зависимость от kotlinx-html-jvm в указанном репозитории и выводятся результаты вызова его функций:

<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>

При первом запуске разрешение зависимостей может занять некоторое время. Последующие запуски будут выполняться намного быстрее, поскольку используют зависимости, загруженные в локальный репозиторий Maven.

Что дальше?

Создав простой проект для скриптинга Kotlin, вы можете узнать больше по этой теме:

• Прочитайте KEEP по скриптингу Kotlin

• Посмотрите другие примеры скриптинга Kotlin

• Посмотрите доклад Родриго Оливейры «Реализация Kotlin DSL для Gradle»