メインコンテンツまでスキップ

マルチプラットフォーム Gradle DSL リファレンス

Kotlin Multiplatform Gradle プラグインは、Kotlin Multiplatform プロジェクトを作成するためのツールです。 ここでは、その内容のリファレンスを提供します。Kotlin Multiplatform プロジェクトの Gradle ビルドスクリプトを作成する際の参考としてください。Kotlin Multiplatform プロジェクトの概念、作成方法、設定方法について学びましょう。

Id とバージョン

Kotlin Multiplatform Gradle プラグインの完全修飾名は org.jetbrains.kotlin.multiplatform です。 Kotlin Gradle DSL を使用している場合は、kotlin("multiplatform") でプラグインを適用できます。 プラグインのバージョンは、Kotlin のリリースバージョンと一致します。最新バージョンは 2.1.20 です。

plugins {
kotlin("multiplatform") version "2.1.20"
}

トップレベルのブロック

kotlin {} は、Gradle ビルドスクリプトにおけるマルチプラットフォームプロジェクト構成のトップレベルブロックです。 kotlin {} 内には、次のブロックを記述できます。

ブロック説明
<targetName>プロジェクトの特定のターゲットを宣言します。利用可能なターゲットの名前は、ターゲットセクションにリストされています。
targetsプロジェクトのすべてのターゲットをリストします。
sourceSetsプロジェクトの事前定義済みおよびカスタムソースセットを設定および宣言します。
compilerOptionsすべてのターゲットと共有ソースセットのデフォルトとして使用される、共通の拡張レベルコンパイラオプションを指定します。

ターゲット

_ターゲット_とは、サポートされているプラットフォームのいずれかを対象としたソフトウェアのコンパイル、テスト、パッケージングを担当するビルドの一部です。Kotlin は各プラットフォームのターゲットを提供しているため、Kotlin にその特定のターゲットに対してコードをコンパイルするように指示できます。ターゲットの設定の詳細をご覧ください。

各ターゲットは、1 つ以上のコンピレーションを持つことができます。テストおよび本番環境用のデフォルトのコンピレーションに加えて、カスタムコンピレーションを作成できます。

マルチプラットフォームプロジェクトのターゲットは、kotlin {} 内の対応するブロックで記述されます。たとえば、jvmandroidTargetiosArm64 などです。 利用可能なターゲットの完全なリストは次のとおりです。

対象プラットフォームターゲットコメント

Kotlin/JVM

jvm

Kotlin/Wasm

wasmJs

JavaScript ランタイムでプロジェクトを実行する予定がある場合は、これを使用します。

wasmWasi

WASI システムインターフェイスのサポートが必要な場合は、これを使用します。

Kotlin/JS

js

実行環境を選択してください。

  • ブラウザで実行されるアプリケーションの場合は browser {}
  • Node.js で実行されるアプリケーションの場合は nodejs {}
  • 詳細については、Kotlin/JS プロジェクトの設定を参照してください。

    Kotlin/Native

    macOS、Linux、Windows ホストで現在サポートされているターゲットについては、Kotlin/Native ターゲットのサポートを参照してください。

    Android アプリケーションおよびライブラリ

    androidTarget

    Android Gradle プラグインを手動で適用します: com.android.application または com.android.library

    Gradle サブプロジェクトごとに作成できる Android ターゲットは 1 つだけです。

    注記

    現在のホストでサポートされていないターゲットは、ビルド中に無視されるため、公開されません。

    kotlin {
    jvm()
    iosArm64()
    macosX64()
    js().browser()
    }

    ターゲットの構成には、次の 2 つの部分を含めることができます。

    各ターゲットは、1 つ以上のコンピレーションを持つことができます。

    共通ターゲット構成

    任意のターゲットブロックでは、次の宣言を使用できます。

    名前説明
    platformTypeこのターゲットの Kotlin プラットフォーム。使用可能な値: jvmandroidJvmjswasmnativecommon
    artifactsTaskNameこのターゲットの結果の成果物をビルドするタスクの名前。
    componentsGradle パブリケーションの設定に使用されるコンポーネント。
    compilerOptionsターゲットに使用されるコンパイラオプション。この宣言は、トップレベルで構成された compilerOptions {} を上書きします。

    Web ターゲット

    js {} ブロックは Kotlin/JS ターゲットの構成を記述し、wasmJs {} ブロックは JavaScript と相互運用可能な Kotlin/Wasm ターゲットの構成を記述します。これらには、ターゲットの実行に応じて、次の 2 つのブロックのいずれかを含めることができます。 環境:

    名前説明
    browserブラウザターゲットの構成。
    nodejsNode.js ターゲットの構成。

    Kotlin/JS プロジェクトの構成の詳細をご覧ください。

    個別の wasmWasi {} ブロックは、WASI システムインターフェイスをサポートする Kotlin/Wasm ターゲットの構成を記述します。 ここでは、nodejs 実行環境のみが利用可能です。

    kotlin {
    wasmWasi {
    nodejs()
    binaries.executable()
    }
    }

    すべての Web ターゲット (jswasmJswasmWasi) は、binaries.executable() 呼び出しもサポートしています。これは、Kotlin コンパイラに実行可能ファイルを出力するように明示的に指示します。詳細については、Kotlin/JS ドキュメントの実行環境を参照してください。

    Browser

    browser {} には、次の構成ブロックを含めることができます。

    名前説明
    testRunsテスト実行の構成。
    runTaskプロジェクトの実行の構成。
    webpackTaskWebpack を使用したプロジェクトバンドルの構成。
    distribution出力ファイルへのパス。
    kotlin {
    js().browser {
    webpackTask { /* ... */ }
    testRuns { /* ... */ }
    distribution {
    directory = File("$projectDir/customdir/")
    }
    }
    }

    Node.js

    nodejs {} には、テストタスクと実行タスクの構成を含めることができます。

    名前説明
    testRunsテスト実行の構成。
    runTaskプロジェクトの実行の構成。
    kotlin {
    js().nodejs {
    runTask { /* ... */ }
    testRuns { /* ... */ }
    }
    }

    Native ターゲット

    Native ターゲットでは、次の特定のブロックが利用可能です。

    名前説明
    binaries生成するバイナリの構成。
    cinteropsC ライブラリとのインターオペラビリティの構成。

    バイナリ

    次の種類のバイナリがあります。

    名前説明
    executable製品の実行可能ファイル。
    testテストの実行可能ファイル。
    sharedLib共有ライブラリ。
    staticLib静的ライブラリ。
    frameworkObjective-C フレームワーク。
    kotlin {
    linuxX64 { // ターゲットを代わりに使用してください。
    binaries {
    executable {
    // バイナリ構成。
    }
    }
    }
    }

    バイナリ構成では、次のパラメーターが利用可能です。

    名前説明
    compilationバイナリの構築元となるコンピレーション。デフォルトでは、test バイナリは test コンピレーションに基づいていますが、他のバイナリは main コンピレーションに基づいています。
    linkerOptsバイナリの構築中にシステムリンカーに渡されるオプション。
    baseName出力ファイルのカスタムベース名。最終的なファイル名は、システム依存のプレフィックスとポストフィックスをこのベース名に追加して形成されます。
    entryPoint実行可能バイナリのエントリーポイント関数。デフォルトでは、ルートパッケージの main() です。
    outputFile出力ファイルへのアクセス。
    linkTaskリンクタスクへのアクセス。
    runTask実行可能バイナリの実行タスクへのアクセス。linuxX64macosX64mingwX64 以外のターゲットの場合、値は null です。
    isStaticObjective-C フレームワークの場合。動的ライブラリの代わりに静的ライブラリを含めます。
    binaries {
    executable("my_executable", listOf(RELEASE)) {
    // テストコンパイルに基づいてバイナリを構築します。
    compilation = compilations["test"]

    // リンカーのカスタムコマンドラインオプション。
    linkerOpts = mutableListOf("-L/lib/search/path", "-L/another/search/path", "-lmylib")

    // 出力ファイルのベース名。
    baseName = "foo"

    // カスタムエントリポイント関数。
    entryPoint = "org.example.main"

    // 出力ファイルへのアクセス。
    println("Executable path: ${outputFile.absolutePath}")

    // リンクタスクへのアクセス。
    linkTask.dependsOn(additionalPreprocessingTask)

    // 実行タスクへのアクセス。
    // runTask はホストプラットフォーム以外では null であることに注意してください。
    runTask?.dependsOn(prepareForRun)
    }

    framework("my_framework" listOf(RELEASE)) {
    // 動的ライブラリの代わりに静的ライブラリをフレームワークに含めます。
    isStatic = true
    }
    }

    Native バイナリのビルドの詳細をご覧ください。

    CInterops

    cinterops は、Native ライブラリとのインターオペラビリティの説明のコレクションです。 ライブラリとのインターオペラビリティを提供するには、cinterops にエントリを追加し、そのパラメーターを定義します。

    名前説明
    definitionFileNative API を記述する .def ファイル。
    packageName生成された Kotlin API のパッケージプレフィックス。
    compilerOptscinterop ツールによってコンパイラに渡されるオプション。
    includeDirsヘッダーを検索するディレクトリ。
    headerバインディングに含めるヘッダー。
    headersバインディングに含めるヘッダーのリスト。
    kotlin {
    linuxX64 { // 必要なターゲットに置き換えてください。
    compilations.getByName("main") {
    val myInterop by cinterops.creating {
    // Native API を記述する Def ファイル。
    // デフォルトのパスは src/nativeInterop/cinterop/<interop-name>.def です。
    definitionFile.set(project.file("def-file.def"))

    // 生成された Kotlin API を配置するパッケージ。
    packageName("org.sample")

    // cinterop ツールによってコンパイラに渡されるオプション。
    compilerOpts("-Ipath/to/headers")

    // ヘッダー検索用のディレクトリ (コンパイラオプション -I<path> の類似)。
    includeDirs.allHeaders("path1", "path2")

    // includeDirs.allHeaders のショートカット。
    includeDirs("include/directory", "another/directory")

    // バインディングに含めるヘッダーファイル。
    header("path/to/header.h")
    headers("path/to/header1.h", "path/to/header2.h")
    }

    val anotherInterop by cinterops.creating { /* ... */ }
    }
    }
    }

    その他の cinterop プロパティについては、定義ファイルを参照してください。

    Android ターゲット

    Kotlin Multiplatform プラグインには、Android ターゲット用の 2 つの特定の関数が含まれています。 2 つの関数は、ビルドバリアントの構成に役立ちます。

    名前説明
    publishLibraryVariants()公開するビルドバリアントを指定します。Android ライブラリの公開の詳細をご覧ください。
    publishAllLibraryVariants()すべてのビルドバリアントを公開します。
    kotlin {
    androidTarget {
    publishLibraryVariants("release")
    }
    }

    Android のコンピレーションの詳細をご覧ください。

    注記

    kotlin {} ブロック内の androidTarget 構成は、Android プロジェクトのビルド構成を置き換えるものではありません。 Android プロジェクトのビルドスクリプトの作成の詳細については、Android デベロッパー向けドキュメントを参照してください。

    ソースセット

    sourceSets {} ブロックは、プロジェクトのソースセットを記述します。ソースセットには、リソース、依存関係、および言語設定とともに、コンピレーションに一緒に参加する Kotlin ソースファイルが含まれています。

    マルチプラットフォームプロジェクトには、ターゲットの事前定義済みソースセットが含まれています。 開発者は、ニーズに合わせてカスタムソースセットを作成することもできます。

    事前定義済みのソースセット

    事前定義済みのソースセットは、マルチプラットフォームプロジェクトの作成時に自動的に設定されます。 利用可能な事前定義済みのソースセットは次のとおりです。

    名前説明
    commonMainすべてのプラットフォーム間で共有されるコードとリソース。すべてのマルチプラットフォームプロジェクトで利用可能です。プロジェクトのすべての main コンピレーションで使用されます。
    commonTestすべてのプラットフォーム間で共有されるテストコードとリソース。すべてのマルチプラットフォームプロジェクトで利用可能です。プロジェクトのすべてのテストコンピレーションで使用されます。
    <targetName><compilationName>コンピレーションのターゲット固有のソース。 <targetName> は事前定義されたターゲットの名前であり、<compilationName> はこのターゲットのコンピレーションの名前です。例: jsTestjvmMain

    Kotlin Gradle DSL では、事前定義済みのソースセットのセクションは by getting でマークする必要があります。

    kotlin {
    sourceSets {
    val commonMain by getting { /* ... */ }
    }
    }

    ソースセットの詳細をご覧ください。

    カスタムソースセット

    カスタムソースセットは、プロジェクト開発者が手動で作成します。 カスタムソースセットを作成するには、sourceSets セクション内にその名前のセクションを追加します。 Kotlin Gradle DSL を使用する場合は、カスタムソースセットを by creating でマークします。

    kotlin { 
    sourceSets {
    val myMain by creating { /* ... */ } // 「MyMain」という名前で新しいソースセットを作成します
    }
    }

    新しく作成されたソースセットは他のソースセットに接続されていないことに注意してください。プロジェクトのコンピレーションで使用するには、 他のソースセットと接続します。

    ソースセットのパラメーター

    ソースセットの構成は、sourceSets {} の対応するブロック内に格納されます。ソースセットには、次のパラメーターがあります。

    名前説明
    kotlin.srcDirソースセットディレクトリ内の Kotlin ソースファイルの場所。
    resources.srcDirソースセットディレクトリ内のリソースの場所。
    dependsOn別のソースセットとの接続
    dependenciesソースセットの依存関係
    languageSettingsソースセットに適用される言語設定
    kotlin { 
    sourceSets {
    val commonMain by getting {
    kotlin.srcDir("src")
    resources.srcDir("res")

    dependencies {
    /* ... */
    }
    }
    }
    }

    コンピレーション

    ターゲットは、本番環境やテストなど、1 つ以上のコンピレーションを持つことができます。事前定義済みのコンピレーションがあります これは、ターゲットの作成時に自動的に追加されます。さらに、カスタムコンピレーションを作成できます。

    ターゲットのすべてまたは一部の特定のコンピレーションを参照するには、compilations オブジェクトコレクションを使用します。 compilations から、名前でコンピレーションを参照できます。

    コンピレーションの構成の詳細をご覧ください。

    事前定義済みのコンピレーション

    事前定義済みのコンピレーションは、Android ターゲットを除く、プロジェクトの各ターゲットに対して自動的に作成されます。 利用可能な事前定義済みのコンピレーションは次のとおりです。

    名前説明
    main本番環境ソースのコンピレーション。
    testテストのコンピレーション。
    kotlin {
    jvm {
    val main by compilations.getting {
    output // メインコンピレーションの出力を取得します
    }

    compilations["test"].runtimeDependencyFiles // テストランタイムクラスパスを取得します
    }
    }

    カスタムコンピレーション

    事前定義済みのコンピレーションに加えて、独自のカスタムコンピレーションを作成できます。 カスタムコンピレーションを作成するには、compilations コレクションに新しいアイテムを追加します。 Kotlin Gradle DSL を使用する場合は、カスタムコンピレーションを by creating でマークします。

    カスタムコンピレーションの作成の詳細をご覧ください。

    kotlin {
    jvm() {
    compilations {
    val integrationTest by compilations.creating {
    defaultSourceSet {
    dependencies {
    /* ... */
    }
    }

    // このコンピレーションによって生成されたテストを実行するテストタスクを作成します。
    tasks.register<Test>("integrationTest") {
    /* ... */
    }
    }
    }
    }
    }

    コンピレーションパラメーター

    コンピレーションには、次のパラメーターがあります。

    名前説明
    defaultSourceSetコンピレーションのデフォルトソースセット。
    kotlinSourceSetsコンピレーションに参加しているソースセット。
    allKotlinSourceSetsコンピレーションに参加しているソースセットと、dependsOn() を介した接続。
    compilerOptionsコンピレーションに適用されるコンパイラオプション。利用可能なオプションのリストについては、コンパイラオプションを参照してください。
    compileKotlinTaskKotlin ソースをコンパイルするための Gradle タスク。
    compileKotlinTaskNamecompileKotlinTask の名前。
    compileAllTaskNameコンピレーションのすべてのソースをコンパイルするための Gradle タスクの名前。
    outputコンピレーションの出力。
    compileDependencyFilesコンピレーションのコンパイル時の依存関係ファイル (クラスパス)。すべての Kotlin/Native コンピレーションの場合、これには標準ライブラリとプラットフォームの依存関係が自動的に含まれます。
    runtimeDependencyFilesコンピレーションのランタイム依存関係ファイル (クラスパス)。
    kotlin {
    jvm {
    val main by compilations.getting {
    compileTaskProvider.configure {
    compilerOptions {
    // 「main」コンピレーションの Kotlin コンパイラオプションを設定します。
    jvmTarget.set(JvmTarget.JVM_1_8)
    }
    }

    compileKotlinTask // Kotlin タスク「compileKotlinJvm」を取得します
    output // メインコンピレーションの出力を取得します
    }

    compilations["test"].runtimeDependencyFiles // テストランタイムクラスパスを取得します
    }

    // すべてのターゲットのすべてのコンピレーションを設定します。
    compilerOptions {
    allWarningsAsErrors.set(true)
    }
    }

    コンパイラオプション

    プロジェクトでは、コンパイラオプションを 3 つの異なるレベルで構成できます。

    • 拡張機能レベル (kotlin {} ブロック内)。
    • ターゲットレベル (ターゲットブロック内)。
    • コンパイルユニットレベル (通常は特定のコンパイルタスク内)。
    Kotlin compiler options levels

    上位レベルの設定は、下位レベルのデフォルトとして機能します。

    • 拡張機能レベルで設定されたコンパイラオプションは、commonMainnativeMaincommonTest などの共有ソースセットを含む、ターゲットレベルオプションのデフォルトです。
    • ターゲットレベルで設定されたコンパイラオプションは、compileKotlinJvm および compileTestKotlinJvm タスクなどの、コンパイルユニット (タスク) レベルのオプションのデフォルトです。

    下位レベルで行われた構成は、上位レベルの同様の設定を上書きします。

    • タスクレベルのコンパイラオプションは、ターゲットレベルまたは拡張機能レベルの同様の設定を上書きします。
    • ターゲットレベルのコンパイラオプションは、拡張機能レベルの同様の設定を上書きします。

    可能なコンパイラオプションのリストについては、すべてのコンパイラオプションを参照してください。

    拡張機能レベル

    プロジェクト内のすべてのターゲットのコンパイラオプションを構成するには、トップレベルで compilerOptions {} ブロックを使用します。

    kotlin {
    // すべてのターゲットのすべてのコンピレーションを構成します
    compilerOptions {
    allWarningsAsErrors.set(true)
    }
    }

    ターゲットレベル

    プロジェクト内の特定のターゲットのコンパイラオプションを構成するには、ターゲットブロック内で compilerOptions {} ブロックを使用します。

    kotlin {
    jvm {
    // JVM ターゲットのすべてのコンピレーションを構成します
    compilerOptions {
    allWarningsAsErrors.set(true)
    }
    }
    }

    コンパイルユニットレベル

    特定のタスクのコンパイラオプションを構成するには、タスク内で compilerOptions {} ブロックを使用します。

    task.named<KotlinJvmCompile>("compileKotlinJvm") {
    compilerOptions {
    allWarningsAsErrors.set(true)
    }
    }

    特定のコンピレーションのコンパイラオプションを構成するには、コンピレーションのタスクプロバイダー内で compilerOptions {} ブロックを使用します。

    kotlin {
    jvm {
    compilations.named(KotlinCompilation.MAIN_COMPILATION_NAME) {
    compileTaskProvider.configure {
    // 「main」コンピレーションを構成します。
    compilerOptions {
    allWarningsAsErrors.set(true)
    }
    }
    }
    }
    }

    依存関係

    ソースセット宣言の dependencies {} ブロックには、このソースセットの依存関係が含まれています。

    依存関係の構成の詳細をご覧ください。

    依存関係には 4 種類あります。

    名前説明
    api現在のモジュールの API で使用される依存関係。
    implementationモジュールで使用されるが、外部には公開されない依存関係。