Kotlinカスタムスクリプトを始める - チュートリアル

注意

Kotlinカスタムスクリプトは試験的です。いつでも削除または変更される可能性があります。評価目的でのみ使用してください。YouTrackでフィードバックをお待ちしております。

Kotlin scripting は、事前にコンパイルしたり、実行可能ファイルにパッケージ化したりせずに、Kotlinコードをスクリプトとして実行できるようにする技術です。

Kotlinスクリプトの概要と例については、KotlinConf'19のRodrigo Oliveiraによる講演Implementing the Gradle Kotlin DSLをご覧ください。

このチュートリアルでは、Mavenの依存関係を持つ任意のKotlinコードを実行するKotlinスクリプトプロジェクトを作成します。次のようなスクリプトを実行できます。

@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!" }
        }
    }
)

指定されたMavenの依存関係（この例ではkotlinx-html-jvm）は、実行中に指定されたMaven リポジトリまたはローカルキャッシュから解決され、スクリプトの残りの部分で使用されます。

プロジェクト構成

最小限のKotlinカスタムスクリプトプロジェクトには、次の2つの部分が含まれています。

スクリプト定義 – このスクリプトタイプを認識、処理、コンパイル、および実行する方法を定義する一連のパラメータと構成。
スクリプトホスト – スクリプトのコンパイルと実行を処理するアプリケーションまたはコンポーネント。実際には、このタイプのスクリプトを実行します。

これらすべてを考慮して、プロジェクトを2つのモジュールに分割するのが最適です。

開始する前に

IntelliJ IDEAの最新バージョンをダウンロードしてインストールします。

プロジェクトを作成する

IntelliJ IDEAで、File | New | Projectを選択します。
左側のパネルで、New Projectを選択します。
新しいプロジェクトに名前を付け、必要に応じて場所を変更します。

Create Git repositoryチェックボックスを選択して、新しいプロジェクトをバージョン管理下に置きます。いつでも実行できます。
Languageリストから、Kotlinを選択します。
Gradleビルドシステムを選択します。
JDKリストから、プロジェクトで使用するJDKを選択します。
- JDKがコンピューターにインストールされていても、IDEで定義されていない場合は、Add JDKを選択し、JDKホームディレクトリへのパスを指定します。
- コンピューターに必要なJDKがない場合は、Download JDKを選択します。
Gradle DSLにKotlinまたはGradle言語を選択します。
Createをクリックします。

スクリプトモジュールを追加する

これで、空のKotlin/JVM Gradleプロジェクトができました。必要なモジュール、スクリプト定義、およびスクリプトホストを追加します。

IntelliJ IDEAで、File | New | Moduleを選択します。
左側のパネルで、New Moduleを選択します。このモジュールはスクリプト定義になります。
新しいモジュールに名前を付け、必要に応じて場所を変更します。
Languageリストから、Javaを選択します。
Gradle DSLにGradleビルドシステムとKotlinを選択します。Kotlinでビルドスクリプトを記述する場合。
モジュールの親として、ルートモジュールを選択します。
Createをクリックします。
モジュールのbuild.gradle(.kts)ファイルで、Kotlin Gradleプラグインのversionを削除します。これは、ルートプロジェクトのビルドスクリプトにすでに存在します。
前の手順をもう一度繰り返して、スクリプトホストのモジュールを作成します。

プロジェクトは次の構造になっている必要があります。

このようなプロジェクトの例、およびその他のKotlinスクリプトの例は、kotlin-script-examples GitHubリポジトリにあります。

スクリプト定義を作成する

まず、スクリプトのタイプを定義します。開発者がこのタイプのスクリプトに何を書くことができ、どのように処理されるかを定義します。このチュートリアルでは、これにはスクリプトの@Repositoryおよび@DependsOnアノテーションのサポートが含まれています。

スクリプト定義モジュールで、build.gradle(.kts)のdependenciesブロックにKotlinスクリプトコンポーネントへの依存関係を追加します。これらの依存関係は、スクリプト定義に必要なAPIを提供します。

Kotlin
Groovy

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.10.1") 
}

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.10.1'

}

モジュールにsrc/main/kotlin/ディレクトリを作成し、Kotlinソースファイル（たとえば、scriptDef.kt）を追加します。
scriptDef.ktで、クラスを作成します。これはこのタイプのスクリプトのスーパークラスになるため、abstractまたはopenとして宣言します。
```
// abstract (or open) superclass for scripts of this type
abstract class ScriptWithMavenDeps
```
このクラスは、後でスクリプト定義への参照としても機能します。
クラスをスクリプト定義にするには、@KotlinScriptアノテーションでマークします。アノテーションに2つのパラメータを渡します。
- fileExtension – このタイプのスクリプトのファイル拡張子を定義する.ktsで終わる文字列。
- compilationConfiguration – ScriptCompilationConfigurationを拡張し、このスクリプト定義のコンパイルの特殊性を定義するKotlinクラス。次のステップで作成します。
```
 // @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()
```
このチュートリアルでは、KotlinスクリプトAPIの説明なしで、動作するコードのみを提供します。詳細な説明付きの同じコードは、GitHubにあります。

次に示すように、スクリプトコンパイル構成を定義します。

 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())

完全なコードはこちらにあります。

スクリプトホストを作成する

次のステップは、スクリプトの実行を処理するコンポーネントであるスクリプトホストを作成することです。

スクリプトホストモジュールで、build.gradle(.kts)のdependenciesブロックに依存関係を追加します。

スクリプトホストに必要なAPIを提供するKotlinスクリプトコンポーネント
以前に作成したスクリプト定義モジュール

Kotlin
Groovy

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
}

モジュールにsrc/main/kotlin/ディレクトリを作成し、Kotlinソースファイル（たとえば、host.kt）を追加します。
アプリケーションのmain関数を定義します。その本文で、引数が1つ（スクリプトファイルへのパス）があることを確認し、スクリプトを実行します。次のステップで、別の関数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)
     }
 }
```
スクリプト評価関数を定義します。ここでは、スクリプト定義を使用します。スクリプト定義クラスを型パラメータとして使用して、createJvmCompilationConfigurationFromTemplateを呼び出すことによって、スクリプト定義を取得します。次に、スクリプトコードとそのコンパイル構成を渡して、BasicJvmScriptingHost().evalを呼び出します。evalはResultWithDiagnosticsのインスタンスを返すため、それを関数の戻り値の型として設定します。
```
 fun evalFile(scriptFile: File): ResultWithDiagnostics<EvaluationResult> {
     val compilationConfiguration = createJvmCompilationConfigurationFromTemplate<ScriptWithMavenDeps>()
     return BasicJvmScriptingHost().eval(scriptFile.toScriptSource(), compilationConfiguration, null)
 }
```

スクリプトの実行に関する情報を出力するように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}")
             }
         }
     }
 }

完全なコードはこちらにあります。

スクリプトを実行する

スクリプトホストがどのように機能するかを確認するには、実行するスクリプトと実行構成を準備します。

次の内容でファイル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!" }
        }
    }
)

@DependsOnアノテーション引数で参照されているkotlinx-html-jvmライブラリの関数を使用します。

スクリプトホストを起動してこのファイルを実行する実行構成を作成します。
1. host.ktを開き、main関数に移動します。左側にRunガターアイコンがあります。
2. ガターアイコンを右クリックし、Modify Run Configurationを選択します。
3. Create Run Configurationダイアログで、スクリプトファイル名をProgram argumentsに追加し、OKをクリックします。
作成された構成を実行します。

スクリプトが実行され、指定されたリポジトリでkotlinx-html-jvmへの依存関係が解決され、その関数の呼び出し結果が出力される様子が表示されます。

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

依存関係の解決には、最初の実行に時間がかかる場合があります。後続の実行では、ローカルのMavenリポジトリからダウンロードした依存関係を使用するため、はるかに高速に完了します。

次は何ですか？

簡単なKotlinスクリプトプロジェクトを作成したら、このトピックに関する詳細情報を検索してください。

KotlinスクリプトKEEPを読む
Kotlinスクリプトの例をさらに参照する
Rodrigo Oliveiraによる講演Implementing the Gradle Kotlin DSLを見る

プロジェクト構成​

開始する前に​

プロジェクトを作成する​

スクリプトモジュールを追加する​

スクリプト定義を作成する​

スクリプトホストを作成する​

スクリプトを実行する​

次は何ですか？​