Kotlin Toolchain

https://kotlin-toolchain.org/0.11/
Admin
A unified entry point for building JVM, Android, iOS, multiplatform, and server-side applications...
Tokens:43,029
Snippets:658
Trust Score:2.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Swift Entry Point Example

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/ios-app

Example of a basic @main struct for an iOS application's entry point in Swift.

```swift
@main
struct iosApp: App {
   ...
}

```

--------------------------------

### Install Kotlin CLI via Installer Script (Windows)

Source: https://kotlin-toolchain.org/0.11/cli

Downloads and installs the Kotlin CLI wrapper script using PowerShell. It places the script in an appropriate location and updates the shell profile to add this directory to your PATH.

```powershell
powershell -ExecutionPolicy ByPass -c "irm 'https://kotl.in/install.ps1' | iex"

```

--------------------------------

### Install Kotlin CLI via Installer Script (Linux/macOS)

Source: https://kotlin-toolchain.org/0.11/cli

Downloads and installs the Kotlin CLI wrapper script using a curl command. It places the script in `~/.local/bin` and updates the shell profile to add this directory to your PATH.

```bash
curl -fsSL https://kotl.in/install.sh | sh

```

--------------------------------

### Install Kotlin CLI via SDKMAN

Source: https://kotlin-toolchain.org/0.11/cli

Installs the Kotlin CLI toolchain using the SDKMAN package manager. The `kotlin` command becomes available on your PATH after installation.

```bash
sdk install kotlintoolchain

```

--------------------------------

### Example Usage of Kotlin Wrapper Script

Source: https://kotlin-toolchain.org/0.11/cli/provisioning

The Kotlin wrapper script allows users to run Kotlin CLI commands without manual installation. Simply check the script into your project's root and execute commands like './kotlin build'.

```bash
./kotlin build
```

--------------------------------

### Toolchain Settings Example

Source: https://kotlin-toolchain.org/0.11/user-guide/basics

Illustrates common toolchain settings for Kotlin language version and Android compilation SDK.

```yaml
settings:
  kotlin:
    languageVersion: 1.8
  android:
    compileSdk: 31


```

--------------------------------

### Shorthand Notation Example

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/configuration

Illustrates the shorthand notation for configuration, where a property marked with @Shorthand allows construction from the value of that property.

```yaml
classpath:
  dependencies: [ "foo:bar:1.0" ]

```

--------------------------------

### YAML List of Strings Example

Source: https://kotlin-toolchain.org/0.11/user-guide/yaml-primer

Illustrates how to define a YAML sequence (list) containing string values. Includes an example of a quoted string within the list.

```yaml
list-name:
  - foo bar
  - "bar baz"
```

--------------------------------

### YAML String Examples

Source: https://kotlin-toolchain.org/0.11/user-guide/yaml-primer

Demonstrates equivalent ways to define strings in YAML: unquoted, double-quoted, and single-quoted.

```yaml
string1: foo bar
string2: "foo bar"
string3: 'foo bar'
```

--------------------------------

### Kotlin/Native Module Layout Example

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/native-app

Illustrates the standard directory structure for a Kotlin/Native application module, including source, test, and configuration files.

```plaintext
my-module/
├─ src/
│  ├─ main.kt 
│  ╰─ Util.kt
├─ test/
│  ╰─ UtilTest.kt
╰─ module.yaml

```

--------------------------------

### KMP Library Module Example

Source: https://kotlin-toolchain.org/0.11/user-guide/basics

Defines a Kotlin Multiplatform library module with platform-specific dependencies and settings.

```yaml
product:
  type: kmp/lib 
  platforms: [android, iosArm64, iosSimulatorArm64] 

dependencies:
  - io.ktor:ktor-client-core:2.3.0 

dependencies@android:
  - io.ktor:ktor-client-android:2.3.0 

dependencies@ios:
  - io.ktor:ktor-client-darwin:2.3.0 

settings: 
  kotlin:
    version: 2.2.21 
    allWarningsAsErrors: true 

settings@ios: 
  kotlin:
    allWarningsAsErrors: false 


```

--------------------------------

### Effective Dependencies for Android (Propagation Example)

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

The resulting dependency list for Android based on the propagation rules in the previous example.

```yaml
dependencies@android:
  ../foo

```

--------------------------------

### Multiplatform Module Layout Example

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

Illustrates a typical directory structure for a Kotlin Multiplatform module, showing how common and platform-specific source sets, resources, and tests are organized using the `@platform` qualifier.

```text
my-module/
├─ resources/       # common resources, used in all targets
├─ resources@ios/   # resources that are only available to the iOS code
├─ resources@jvm/   # resources that are only available to the JVM code
├─ src/             # common code, compiled for all targets
│  ├─ main.kt
│  ╰─ util.kt 
├─ src@native/      # code to be compiled for all native targets
├─ src@apple/       # code to be compiled for all Apple targets
├─ src@ios/         # code to be compiled only for iOS targets
│  ╰─ util.kt 
├─ src@jvm/         # code to be compiled only for JVM targets
│  ├─ util.kt
│  ╰─ MyClass.java 
├─ test/            # common tests, compiled for all targets
│  ╰─ MainTest.kt   
├─ test@ios/        # tests that are only run on iOS simulator
│  ╰─ SomeIosTest.kt
├─ test@jvm/        # tests that are only run on JVM
│  ╰─ SomeJvmTest.kt
├─ testResources/       # common test resources, used in all targets
├─ testResources@ios/   # test resources that are only available to the iOS code
├─ testResources@jvm/   # test resources that are only available to the JVM code
╰─ module.yaml
```

--------------------------------

### YAML List of Mappings Example

Source: https://kotlin-toolchain.org/0.11/user-guide/yaml-primer

Demonstrates a YAML sequence containing mappings. Shows both a named mapping and an inline mapping within the list.

```yaml
list-name:
  - named-mapping:
      field1: x
      field2: y
  - field1: x
    field2: y
```

--------------------------------

### YAML Mapping Example

Source: https://kotlin-toolchain.org/0.11/user-guide/yaml-primer

Shows a basic YAML mapping with nested key-value pairs and a numeric value.

```yaml
mapping-name:
  field1: foo bar
  field2: 1.2
```

--------------------------------

### Project Configuration for Modularization

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Define the modules for your project in the root project.yaml file. This example includes a jvm-app and a shared module.

```yaml
modules:
  - ./jvm-app
  - ./shared


```

--------------------------------

### Adding a Multiplatform Library Dependency

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

Example of adding a multiplatform library (KmLogging) to a project, showing the general dependency declaration.

```yaml
product:
  type: kmp/lib
  platforms: [android, iosArm64, jvm]

dependencies:
  - com.diamondedge:logging:2.1.0

```

--------------------------------

### JVM Application Module Example

Source: https://kotlin-toolchain.org/0.11/user-guide/basics

Defines a module that produces a JVM application. Includes Ktor client dependency and Kotlin version settings.

```yaml
product: jvm/app 

dependencies:
  - io.ktor:ktor-client-java:2.3.0 

settings: 
  kotlin:
    version: 2.2.21 
    allWarningsAsErrors: true 


```

--------------------------------

### App Module Configuration

Source: https://kotlin-toolchain.org/0.11/user-guide/basics

Configures a specific module, defining its product type and dependencies on other modules. This example shows an application module.

```yaml
product: jvm/app

dependencies:
  - ./libs/lib1
  - ./libs/lib2

```

--------------------------------

### Task execution error output

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/quick-start

Example of a build failure message when a required properties file is missing.

```text
ERROR: Task ':app:generate@build-config' failed: java.lang.IllegalStateException: The file /path/to/project/app/config.properties does not exist
        at com.example.GenerateSourcesKt.generateSources(generateSources.kt:19)
```

--------------------------------

### Example Maven Plugin Output Directory Structure

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/maven-plugins

Illustrates the typical directory structure for files produced by Maven plugins within the Kotlin Toolchain build output. Report mojos also generate HTML files in a 'reports' subdirectory.

```text
build/
└── maven-target/
    ├── jacoco.exec
    └── reports/
        └── checkstyle.html

```

--------------------------------

### Kotlin/JS Module Layout Example

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/js-app

This snippet illustrates the typical directory structure for a Kotlin/JS application module, including source files, test files, and configuration.

```yaml
my-module/
├─ src/
│  ├─ main.kt
│  ╰─ Util.kt
├─ test/
│  ╰─ UtilTest.kt
╰─ module.yaml

```

--------------------------------

### Effective Dependencies for iOS Simulator Arm64 (Propagation Example)

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

The resulting dependency list for iOS Simulator Arm64 based on the propagation rules, including alias inheritance.

```yaml
dependencies@iosSimulatorArm64:
  ../foo
  ../bar

```

--------------------------------

### Define Target Platforms for a KMP Library

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

Example of specifying the target platforms for a Kotlin Multiplatform library using the `product.platforms` list in a configuration file. Only platform names, not family names, are allowed.

```yaml
product:
  type: kmp/lib
  platforms: [iosArm64, android, jvm]
```

--------------------------------

### Enable and Configure Plugin for a Module

Source: https://kotlin-toolchain.org/0.11/reference/project

To enable and configure a plugin for a specific module, use the 'plugins' block within that module's 'module.yaml' file. This example shows how to enable 'my-plugin'.

```yaml
plugins:
  my-plugin:
    enabled: true
    # plugin-specific settings here
```

--------------------------------

### Multi-Module Project with Root Module Layout

Source: https://kotlin-toolchain.org/0.11/user-guide/basics

Demonstrates a multi-module project structure that includes a root module alongside other modules. This setup is generally discouraged.

```yaml
├─ lib/
│  ├─ src/
│  │  ╰─ util.kt
│  ╰─ module.yaml
├─ src/  # src of the root module
│  ├─ main.kt
│  ╰─ ...
├─ module.yaml  # the module file of the root module
╰─ project.yaml

```

--------------------------------

### Object Type Default Values Example

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/configuration

Demonstrates default values for properties of object types, showing which types can be instantiated by default and which require explicit defaults.

```kotlin
@Configurable interface SomeSettings {
    val foo: Foo  // has default - `Foo` can be instantiated by default
    val bar: Bar  // no default - `Bar` has required properties
}

@Configurable interface Foo {
    val quu1: String get() = "hello"  // (has default - optional in YAML)
}

@Configurable interface Bar {
    val quu2: String  // (no default - required in YAML)
}

```

--------------------------------

### Apply a Module Template

Source: https://kotlin-toolchain.org/0.11/reference/module

Apply a template to the current module using relative paths. This example applies a common template from a parent directory.

```yaml
# Apply a `common.module-template.yaml` template to the module
product: jvm/app

apply:
  - ../common.module-template.yaml

```

--------------------------------

### Effective Dependencies for iOS Arm64 (Propagation Example)

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

The resulting dependency list for iOS Arm64 based on the propagation rules, including specific platform overrides.

```yaml
dependencies@iosArm64:
  ../foo
  ../bar
  ../baz

```

--------------------------------

### Configure Java Annotation Processors with Options

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/java-annotation-processing

Customize annotation processors by passing options using the `processorOptions` map. This example uses a catalog reference for the processor and sets a debug option.

```yaml
settings:
  java:
    annotationProcessing:
      processors:
        - $libs.auto.service # using catalog reference 
      processorOptions:
        debug: true

```

--------------------------------

### Power Assert Example with Custom Message

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/kotlin-compiler-plugins

Demonstrates the output of a failed assertion using Power Assert, showing variable values and the custom error message.

```kotlin
assert(hello.length == world.substring(1, 4).length) { "Incorrect length" }

```

--------------------------------

### Reference Resolution Example

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/references

Illustrates how Kotlin Toolchain references are resolved by searching upward in lexical scopes for the starting part and then resolving subsequent parts as member-properties. Implicit properties like defaults and reference-only properties are considered in scopes.

```yaml
sibling-object:
  foo: 1
  bar: 4 # scopes here: 
object:
  # foo: 1 (by default)
  # provided: 2 (reference-only)
  list:
    - quu: 'a'
      buu: 'b' # scopes here: 
  baz: 3
  bar: 4 # scopes here: 
```

--------------------------------

### Basic main.kt for Hello World

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

The entry point for a simple 'Hello, World!' JVM application. This code prints a greeting to the console.

```kotlin
fun main() {
    println("Hello, World!")
}
```

--------------------------------

### Run Project Conversion Tool

Source: https://kotlin-toolchain.org/0.11/getting-started/migrating-from-maven

Execute the Kotlin Toolchain's project conversion command.

```bash
kotlin tool convert-project

```

--------------------------------

### Project structure with main.kt and module.yaml

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Illustrates the basic file structure of a Kotlin project, including source files and configuration.

```text
├─ src/
│  ╰─ main.kt
╰─ module.yaml
```

--------------------------------

### Explore Kotlin CLI Help

Source: https://kotlin-toolchain.org/0.11/cli

Displays available commands and general options for the Kotlin CLI. Use `--help` with specific subcommands to see their options.

```bash
kotlin --help       # shows the available commands and general options
kotlin build --help # shows the options for the 'build' command specifically

```

--------------------------------

### Basic Compose Desktop Application

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

A minimal Kotlin application using Compose Multiplatform to display 'Hello, World!' in a window. Ensure Compose dependencies are configured.

```kotlin
import androidx.compose.foundation.text.BasicText
import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application

fun main() = application {
    Window(onCloseRequest = ::exitApplication) {
        BasicText("Hello, World!")
    }
}


```

--------------------------------

### Define Repositories with Credentials

Source: https://kotlin-toolchain.org/0.11/reference/module

Sets up repositories with credentials loaded from a properties file for authentication.

```kotlin
repositories:
  - url: https://my.private.repository/
    credentials:
      file: ./local.properties
      usernameKey: my.private.repository.username
      passwordKey: my.private.repository.password  

```

--------------------------------

### Task Action Example with Module Reference

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/references

This example demonstrates a potential name clash when referencing `module` within a task's action. The resolution might incorrectly pick up a local `module` property instead of the intended root scope reference, leading to cyclic errors. Avoid such name clashes.

```yaml
action: !myAction
  module: ${module.name}
```

--------------------------------

### Enable and Configure Plugin in module.yaml (Expanded)

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/structure

Enable a plugin and provide specific settings by using a map for the plugin ID in module.yaml. Set 'enabled: true' and add other configuration options as needed.

```yaml
plugins:
  <plugin-id>:
    enabled: true
    # other options
```

--------------------------------

### Custom Entry Point Configuration

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/native-app

Shows how to specify a custom entry point function for a Kotlin/Native application in the module settings when not using the default 'main.kt'.

```yaml
product: linux/app

settings:
  native:
    entryPoint: org.example.myapp.myMainFun 

```

--------------------------------

### Enable Ktor Support

Source: https://kotlin-toolchain.org/0.11/user-guide/builtin-tech/ktor

Add this to your `module.yaml` to enable basic Ktor support. This applies the Ktor BOM, adds Ktor entries to the library catalog, and sets `io.ktor.development=true` for `kotlin run`.

```yaml
settings:
  ktor: enabled

```

--------------------------------

### Android-Specific Parcelable Type Alias

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/android-app

In Android code, define 'MyParcelable' as a type alias for 'android.os.Parcelable' to work with the custom annotation setup.

```kotlin
actual typealias MyParcelable = android.os.Parcelable

```

--------------------------------

### Project structure with Java and Kotlin files

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Shows a project structure that includes both Kotlin and Java source files, demonstrating co-existence.

```text
├─ src/
│  ├─ main.kt
│  ╰─ JavaClass.java
├─ kotlin
├─ kotlin.bat
╰─ module.yaml
```

--------------------------------

### Example Parcelable Class with @Parcelize

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/android-app

A data class annotated with @Parcelize to automatically generate Parcelable implementation. Requires the Parcelize feature to be enabled.

```kotlin
import kotlinx.parcelize.Parcelize

@Parcelize
class User(val firstName: String, val lastName: String, val age: Int): Parcelable

```

--------------------------------

### Using Project Catalog Dependencies (module.yaml)

Source: https://kotlin-toolchain.org/0.11/user-guide/dependencies

Reference dependencies from the project catalog using the '$libs.<key>' syntax in your module configuration.

```yaml
dependencies:
  - $libs.ktor.client.auth
  - $libs.ktor.client.cio
  - $libs.ktor.client.contentNegotiation

```

--------------------------------

### Defining Platform Aliases and Dependencies

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

Demonstrates how to define custom platform aliases (e.g., jvmAndAndroid) and apply shared dependencies and settings to these aliases.

```yaml
product:
  type: kmp/lib
  platforms: [iosArm64, android, jvm]

aliases:
  - jvmAndAndroid: [jvm, android] # defines a custom alias for this group of platforms

# these dependencies will be visible in jvm and android code
dependencies@jvmAndAndroid:
  - org.lighthousegames:logging:1.3.0

# these dependencies will be visible in jvm code only
dependencies@jvm:
  - org.lighthousegames:logging:1.3.0

# these settings will affect both jvm and android code, and the shared code placed in src@jvmAndAndroid
settings@jvmAndAndroid:
  kotlin:
    freeCompilerArgs: [ -jvm-default=no-compatibility ]

```

--------------------------------

### Configure Metro Compiler Plugin

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/kotlin-compiler-plugins

Example of configuring the Metro compiler plugin. The plugin ID is found in the `CommandLineInterface` implementation of the compiler plugin.

```kotlin
settings:
  kotlin:
    compilerPlugins:
      # The compiler plugin ID is found in the CommandLineInterface implementation of the compiler plugin:
      # https://github.com/ZacSweers/metro/blob/b927d128fa57becc83b5ce13621255b96aca12ad/compiler/src/main/kotlin/dev/zacsweers/metro/compiler/MetroCommandLineProcessor.kt#L12
      - id: dev.zacsweers.metro.compiler
        dependency: dev.zacsweers.metro:compiler:0.11.4
        options: 
          enabled: true
          debug: false

```

--------------------------------

### Declare Local Module Dependencies

Source: https://kotlin-toolchain.org/0.11/user-guide/dependencies

Declare dependencies on other modules within your project using relative paths starting with `./` or `../` in `app/module.yaml`.

```yaml
product: jvm/app

dependencies:
- ./nested-lib
- ../ui/utils

```

--------------------------------

### Example of Exported Dependency

Source: https://kotlin-toolchain.org/0.11/user-guide/dependencies

Mark dependencies as 'exported' if their types are used in your module's public API. This ensures consumers can see them at compile time.

```java
class MyApi(private val client: HttpClient) {
    // ...
}

```

--------------------------------

### Build and Run iOS App

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Command to build and run the iOS application from the command line.

```bash
./kotlin run -m ios-app

```

--------------------------------

### Configure Koin Compiler Plugin

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/kotlin-compiler-plugins

Example of configuring the Koin compiler plugin. The plugin ID is typically found in the `CommandLineInterface` implementation of the compiler plugin.

```kotlin
settings:
  kotlin:
    compilerPlugins:
      # The compiler plugin ID is found in the CommandLineInterface implementation of the compiler plugin, but this is
      # actually coming from the build file in this case:
      # https://github.com/InsertKoinIO/koin-compiler-plugin/blob/75d838fd3ddfabfe34170418573a08fb8766cab8/koin-compiler-plugin/build.gradle.kts#L55
      - id: io.insert-koin.compiler.plugin
        dependency: io.insert-koin:koin-compiler-plugin:0.3.0

```

--------------------------------

### Dependency Propagation with Platform-Specific Overrides

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

Demonstrates how general dependencies and platform-specific dependencies propagate through different platform configurations, including aliases.

```yaml
product:
  type: kmp/lib
  platforms: [android, iosArm64, iosSimulatorArm64]

dependencies:
  - ../foo
dependencies@ios:
  - ../bar
dependencies@iosArm64:
  - ../baz

```

--------------------------------

### Project structure with test folder

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Illustrates the project structure including a dedicated folder for test files. This is where test code should reside.

```text
├─ src/
│  ╰─ ...
├─ test/
│  ╰─ MyTest.kt
├─ kotlin
├─ kotlin.bat
╰─ module.yaml
‎
```

--------------------------------

### Create an Alias for Shared Code

Source: https://kotlin-toolchain.org/0.11/reference/module

Define an alias to share code, dependencies, and settings between multiple platforms. This example shares configurations between JVM and Android.

```yaml
product:
  type: kmp/lib
  platforms: [ jvm, android, iosArm64, iosSimulatorArm64 ]

aliases:
  - jvmAndAndroid: [jvm, android]

# Dependencies for JVM and Android platforms:
dependencies@jvmAndAndroid:
  ...
```

--------------------------------

### Build and Run Android App

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Command to build and run the Android application from the command line.

```bash
./kotlin run -m android-app

```

--------------------------------

### Maven-like Module Directory Structure

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/maven-like-layout

Illustrates the standard directory structure for a module using the Maven-like layout, including source, resource, and test directories for both Java and Kotlin.

```yaml
module/
├── module.yaml
└── src/
    ├── main/
    │   ├── java/
    │   │   └── Main.java
    │   ├── kotlin/
    │   │   └── func.kt
    │   └── resources/
    │       └── input.txt
    └── test/
        ├── java/
        │   └── JavaTest.java
        ├── kotlin/
        │   └── KotlinTest.kt
        └── resources/
            └── test-input.txt

```

--------------------------------

### Enable Spring Boot Support

Source: https://kotlin-toolchain.org/0.11/user-guide/builtin-tech/spring

Add this configuration to your `module.yaml` file to enable basic Spring Boot support. This applies the Spring Boot BOM, starter dependencies, and configures Kotlin compiler plugins.

```yaml
settings:
  springBoot: enabled

```

--------------------------------

### Reference-only Properties in Root Scope

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/references

Shows an example of reference-only properties available in the root scope for use in plugin.yaml configuration. These properties are provided by the Kotlin Toolchain itself.

```yaml
# module: { ... }
```

--------------------------------

### Publishing Command

Source: https://kotlin-toolchain.org/0.11/user-guide/publishing

Execute this command to publish all modules that have publishing enabled and a configured repository with the specified ID.

```bash
kotlin publish someIdOfYourChoosing

```

--------------------------------

### Overriding Language Version for Tests

Source: https://kotlin-toolchain.org/0.11/user-guide/testing

Provides an example of overriding the `languageVersion` setting for tests using `test-settings` in `module.yaml`, demonstrating how test configurations can differ from main configurations.

```yaml
product:
  type: kmp/lib
  platforms: [android, iosArm64]

# these dependencies are available in main and test code
dependencies:
  - io.ktor:ktor-client-core:2.2.0

# dependencies for test code
test-dependencies:
  - org.jetbrains.kotlin:kotlin-test:1.8.10

# these settings affect the main and test code
settings: 
  kotlin:
    languageVersion: 1.8

# these settings affect tests only
test-settings:
  kotlin:
    languageVersion: 1.9 # overrides settings.kotlin.languageVersion 1.8

```

--------------------------------

### Configurable Interface for Distribution

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/tasks

Defines a configurable interface named Distribution with manifestPath and binaryPath properties of type Path. This example illustrates how custom interfaces can be used to specify file inputs for task actions.

```kotlin
@Configurable interface Distribution {
  val manifestPath: Path
  val binaryPath: Path
}

```

--------------------------------

### iOS Application Entry Point Structure

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/ios-app

The entry point for an iOS application is a @main struct within a Swift file in the src directory.

```plaintext
├─ src/
│  ├─ main.swift
│  ╰─ ...
├─ module.yaml
╰─ module.xcodeproj

```

--------------------------------

### Configure Unknown Maven Plugins

Source: https://kotlin-toolchain.org/0.11/getting-started/migrating-from-maven

Example configuration for handling unknown Maven plugins like maven-enforcer-plugin and jacoco-maven-plugin within the Kotlin Toolchain's module.yaml. By default, these plugins are disabled and require explicit enabling.

```yaml
mavenPlugins:
  maven-enforcer-plugin.enforce:
    enabled: false
    configuration:
      rules: |-
        <rules>
          <requireJavaVersion>
            <version>17</version>
          </requireJavaVersion>
        </rules>
  jacoco-maven-plugin.prepare-agent:
    enabled: false

```

--------------------------------

### Define macOS Application Product (Full Form)

Source: https://kotlin-toolchain.org/0.11/reference/module

Explicitly defines the product type as a macOS application and specifies the target platforms.

```kotlin
product:
  type: macos/app
  platforms: [ macosArm64, macosArm64 ]

```

--------------------------------

### Enable Compose with Short Form

Source: https://kotlin-toolchain.org/0.11/reference/module

Enables the Compose Multiplatform runtime, dependencies, and compiler plugins using a concise setting.

```yaml
settings:
  compose: enabled
```

--------------------------------

### Define macOS Application Product (Short Form)

Source: https://kotlin-toolchain.org/0.11/reference/module

Specifies the product type as a macOS application using the short form. Defaults to all supported platforms for the target.

```kotlin
# Defaults to all supported platforms for the corresponding target
product: macos/app

```

--------------------------------

### Use kotlinx-datetime in main.kt

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Demonstrates using the kotlinx-datetime library to print the current date and time. Requires the dependency to be declared in module.yaml.

```kotlin
import kotlinx.datetime.*

fun main() {
    println("Hello, World!")
    println("It's ${Clock.System.now().toLocalDateTime(TimeZone.currentSystemDefault())} here")
}
```

--------------------------------

### Define Repositories (Full Form)

Source: https://kotlin-toolchain.org/0.11/reference/module

Configures repositories with explicit URLs and optional IDs for dependency resolution.

```kotlin
repositories:
  - url: https://repo.spring.io/ui/native/release
  - id: jitpack
    url: https://jitpack.io

```

--------------------------------

### Minimal Configuration for Desktop Application

Source: https://kotlin-toolchain.org/0.11

This is the minimal configuration for a desktop application. It specifies the product type and includes a shared module.

```yaml
product: jvm/app
dependencies:
  - ../shared
settings:
  compose: enabled

```

--------------------------------

### Enable Kotlinx RPC Support

Source: https://kotlin-toolchain.org/0.11/user-guide/builtin-tech/kotlinx-rpc

Add this configuration to your `module.yaml` file to enable kotlinx.rpc support for client, server, or service modules. This activates code generation, applies the RPC BOM, and adds library catalog entries.

```yaml
settings:
  kotlin:
    rpc: enabled

```

--------------------------------

### Single-Module Project Layout

Source: https://kotlin-toolchain.org/0.11/user-guide/basics

Illustrates the directory structure for a basic single-module Kotlin project. No `project.yaml` is required in this configuration.

```yaml
my-project/ 
├─ src/
│  ├─ main.kt
├─ test/
│  ╰─ MainTest.kt
╰─ module.yaml

```

--------------------------------

### Enable Parcelize with Short Form

Source: https://kotlin-toolchain.org/0.11/reference/module

Enables Parcelize to process @Parcelize-annotated classes using a simple configuration.

```yaml
settings:
  android:
    parcelize: enabled
```

--------------------------------

### Configure Fallback JDK Distributions

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/jdk-provisioning

Set a list of acceptable JDK distributions, including fallbacks for platforms where a preferred distribution might not be available.

```yaml
settings:
  jvm:
    jdk:
      distributions: [corretto, microsoft]

```

--------------------------------

### KMP Library Module Layout

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/kmp-lib

Illustrates the directory structure for a Kotlin Multiplatform library, showing common and target-specific resource and source sets.

```text
my-module/
├─ resources/       # common resources, used in all targets
├─ resources@ios/   # resources that are only available to the iOS code
├─ resources@jvm/   # resources that are only available to the JVM code
├─ src/             # common code, compiled for all targets
│  ├─ main.kt
│  ╰─ util.kt 
├─ src@native/      # code to be compiled for all native targets
├─ src@apple/       # code to be compiled for all Apple targets
├─ src@ios/         # code to be compiled only for iOS targets
│  ╰─ util.kt 
├─ src@jvm/         # code to be compiled only for JVM targets
│  ├─ util.kt
│  ╰─ MyClass.java 
├─ test/            # common tests, compiled for all targets
│  ╰─ MainTest.kt   
├─ test@ios/        # tests that are only run on iOS simulator
│  ╰─ SomeIosTest.kt
├─ test@jvm/        # tests that are only run on JVM
│  ╰─ SomeJvmTest.kt
├─ testResources/       # common test resources, used in all targets
├─ testResources@ios/   # test resources that are only available to the iOS code
├─ testResources@jvm/   # test resources that are only available to the JVM code
╰─ module.yaml

```

--------------------------------

### Complex Platform Settings Specialization

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

Demonstrates advanced specialization of settings for different iOS platforms (iOS, iOS Arm64, iOS Simulator Arm64) using `@platform`-qualifiers.

```yaml
product:
  type: kmp/lib
  platforms: [android, iosArm64, iosSimulatorArm64]

settings:           # common toolchain settings
  kotlin:           # Kotlin toolchain
    languageVersion: 1.8
    freeCompilerArgs: [x]
  android:              # Android toolchain
    compileSdk: 33

settings@android:   # specialization for Android platform
  compose: enabled  # Compose toolchain

settings@ios:       # specialization for all iOS platforms
  kotlin:           # Kotlin toolchain
    languageVersion: 1.9
    freeCompilerArgs: [y]

settings@iosArm64:  # specialization for iOS arm64 platform 
  kotlin:           # Kotlin toolchain
    freeCompilerArgs: [z]

```

--------------------------------

### Project Structure for Testing

Source: https://kotlin-toolchain.org/0.11/user-guide/testing

Illustrates the typical directory structure for a Kotlin project, highlighting the location of production code and test code.

```yaml
├─ src/            # production code
├─ test/           # test code
│  ├─ MainTest.kt
│  ╰─ ...
╰─ module.yaml

```

--------------------------------

### Define Repositories (Short Form)

Source: https://kotlin-toolchain.org/0.11/reference/module

Specifies a list of repository URLs for dependency resolution using the short form.

```kotlin
repositories:
  - https://repo.spring.io/ui/native/release 
  - https://jitpack.io

```

--------------------------------

### Enable All-open Plugin with Framework Presets

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/kotlin-compiler-plugins

Use preconfigured presets for the All-open plugin to automatically include annotations for specific frameworks like Spring or Micronaut.

```yaml
settings:
  kotlin:
    allOpen:
      enabled: true
      presets:
        - spring
        - micronaut

```

--------------------------------

### Template precedence and merging

Source: https://kotlin-toolchain.org/0.11/user-guide/templates

Demonstrates how module.yaml settings override template values and how lists are merged.

```yaml
dependencies:
  - ../shared

settings:
  kotlin:
    languageVersion: 1.8
  compose: enabled
```

```yaml
product: jvm/app

apply:
  - ./common.module-template.yaml

dependencies:
  - ../jvm-util

settings:
  kotlin:
    languageVersion: 1.9
  jvm:
    release: 8
```

```yaml
product: jvm/app

dependencies:  # lists appended
  - ../shared
  - ../jvm-util

settings:  # objects merged
  kotlin:
    languageVersion: 1.9  # module.yaml overwrites value
  compose: enabled        # from the template
  jvm:
    release: 8   # from the module.yaml
```

--------------------------------

### Enable Maven-like Layout in module.yaml

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/maven-like-layout

Configuration snippet to enable the Maven-like module layout by setting the 'layout' property in the module.yaml file.

```yaml
layout: maven-like

```

--------------------------------

### Configure Compose with Resources

Source: https://kotlin-toolchain.org/0.11/reference/module

Enables Compose Multiplatform, specifies the version, and configures resource handling. This includes setting a package name and controlling accessor exposure.

```yaml
settings:
  compose:
    enabled: true
    version: 1.6.10
    resources:
      packageName: "com.example.myapp.resources"
      exposedAccessors: true
```

--------------------------------

### Implement a printSources task

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/quick-start

A task action that reads and prints the contents of generated source files.

```kotlin
package com.example

// import ...

@TaskAction
fun printSources(
  @Input sourceDir: Path,
) {
  sourceDir.walk().forEach { file ->
    println(file.pathString)
    println(file.readText())
  }
}
```

--------------------------------

### Apply a template to a module

Source: https://kotlin-toolchain.org/0.11/user-guide/templates

Reference a template file in the apply section of a module.yaml file.

```yaml
product: jvm/app

apply: 
  - ../common.module-template.yaml
```

```yaml
test-dependencies:
  - org.jetbrains.kotlin:kotlin-test:1.8.10

settings:
  kotlin:
    languageVersion: 1.8
```

--------------------------------

### Configure Native Application Entry Point

Source: https://kotlin-toolchain.org/0.11/reference/module

Configures settings specific to native applications by specifying the fully-qualified name of the application's entry point function.

```yaml
# Configure native settings for the module
settings:
  native:
    entryPoint: com.example.MainKt.main
```

--------------------------------

### Register Task in plugin.yaml

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/quick-start

Defining the task and mapping the action to specific input and output paths.

```yaml
tasks:
  generate: 
    action: !com.example.generateSources
      propertiesFile: ${module.rootDir}/config.properties 
      generatedSourceDir: ${taskOutputDir}
```

--------------------------------

### Register Plugin in project.yaml

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/structure

List the plugin's path in the 'plugins' section of project.yaml to make it available project-wide. This is separate from enabling it in specific modules.

```yaml
modules:
  - ...
  - plugins/my-plugin

plugins:
  - ./plugins/my-plugin
```

--------------------------------

### Configure plugin settings

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/quick-start

Define generated source directories in the plugin configuration.

```yaml
generated:
  sources:
    - language: kotlin
      directory: ${tasks.generate.action.generatedSourceDir}
```

--------------------------------

### Configure Compose with Version

Source: https://kotlin-toolchain.org/0.11/reference/module

Enables Compose Multiplatform and specifies the plugin version to use. This is a more detailed configuration than the short form.

```yaml
settings:
  compose:
    enabled: true
    version: 1.6.10
```

--------------------------------

### Configure Compose Dependencies in module.yaml

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Add Compose Multiplatform dependencies and enable the Compose framework toolchain in your module.yaml file.

```yaml
product: jvm/app

dependencies:
  # ...other dependencies...

  # add Compose dependencies
  - $compose.foundation
  - $compose.material3
  - $compose.desktop.currentOs

settings:
  # ...other settings...

  # enable the Compose framework toolchain  
  compose:
    enabled: true


```

--------------------------------

### Consumer Module Configuration with KSP Processor

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/ksp

Sets up a JVM application module to use a custom KSP processor by referencing its module path in the settings.

```yaml
product: jvm/app

dependencies:
  - ../my-processor-annotations # to be able to annotate the consumer code

settings:
  kotlin:
    ksp:
      processors:
        - ../my-processor # path to the module implementing the KSP processor
```

--------------------------------

### Create module.yaml for JVM App

Source: https://kotlin-toolchain.org/0.11/getting-started/tutorial

Defines a new JVM application project. This is the initial configuration file for the project.

```yaml
product: jvm/app
```

--------------------------------

### Enable Plugin in module.yaml (Shorthand)

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/structure

Enable a plugin in a specific module by listing its ID in the 'plugins' section of module.yaml. This uses the default configuration.

```yaml
plugins:
  <plugin-id>: enabled
```

--------------------------------

### Enable Power Assert Plugin

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/kotlin-compiler-plugins

Configure the Kotlin Toolchain to enable the Power Assert plugin for enhanced assertion failure output.

```yaml
settings:
  kotlin:
    powerAssert: enabled

```

--------------------------------

### AndroidManifest.xml Entry Point Configuration

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/android-app

Defines the application's entry point by specifying the main activity within the AndroidManifest.xml file. This is crucial for Android to launch your application correctly.

```xml
<manifest ... >
  <application ... >
    <activity android:name="com.example.myapp.MainActivity" ... >
    </activity>
  </application>
</manifest>

```

--------------------------------

### Use Local Maven Repository

Source: https://kotlin-toolchain.org/0.11/reference/module

Configures the build to use the local Maven repository (`~/.m2/repository`) for dependency lookups.

```kotlin
repositories:
  - mavenLocal # special URL that points to ~/.m2/repository

```

--------------------------------

### Run a Specific Custom Command

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/topics/custom-commands

Execute a custom command by its name using the 'do' command. Use './kotlin show commands' to list available commands.

```bash
./kotlin do updateDetektBaseline

```

--------------------------------

### Xcode Build Phase Script for Kotlin Integration

Source: https://kotlin-toolchain.org/0.11/user-guide/product-types/ios-app

This script is a build phase in Xcode that integrates with the Kotlin Toolchain. It should not be edited manually.

```bash
# !AMPER KMP INTEGRATION STEP!
# This script is managed by the Kotlin Toolchain, do not edit manually!
"${KOTLIN_CLI_WRAPPER_PATH}" tool xcode-integration

```

--------------------------------

### Effective iOS Arm64 Settings Calculation

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

Shows the effective settings for the iOS Arm64 platform, demonstrating merged Kotlin compiler arguments from common and iOS-specific settings.

```yaml
settings@iosArm64:
  kotlin:
    languageVersion: 1.9      # from settings@ios:
    freeCompilerArgs: [x, y]  # merged from settings: and settings@ios:

```

--------------------------------

### Execute a task via CLI

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/quick-start

Run a specific task manually using the Kotlin Toolchain CLI.

```bash
./kotlin task :app:print@build-config
```

--------------------------------

### Set Module Layout to Maven-like

Source: https://kotlin-toolchain.org/0.11/reference/module

Configures the module to use a Maven-like directory structure. This layout is supported for `jvm/app` or `jvm/lib` product types.

```kotlin
product: jvm/app

layout: maven-like

settings:
  # ...

```

--------------------------------

### Platform-Specific Source Directory Hierarchy

Source: https://kotlin-toolchain.org/0.11/user-guide/multiplatform

Illustrates the hierarchy of source directories in a Kotlin Multiplatform project, showing how code visibility increases with platform specificity.

```yaml
├─ src/
├─ src@native/            # sees declarations from src
├─ src@apple/             # sees declarations from src + src@native
├─ src@ios/               # sees declarations from src + src@native + src@apple
├─ src@iosArm64/          # sees declarations from src + src@native + src@apple + src@ios
├─ src@iosSimulatorArm64/ # sees declarations from src + src@native + src@apple + src@ios
├─ src@jvm/               # sees declarations from src
╰─ module.yaml

```

--------------------------------

### Multi-Module Project Layout

Source: https://kotlin-toolchain.org/0.11/user-guide/basics

Shows the directory structure for a multi-module Kotlin project. The `project.yaml` file lists all included modules.

```yaml
├─ app/
│  ├─ src/
│  │  ├─ main.kt
│  │  ╰─ ...
│  ╰─ module.yaml
├─ libs/ 
│  ├─ lib1/
│  │  ├─ src/
│  │  │  ╰─ myLib1.kt
│  │  ╰─ module.yaml
│  ╰─ lib2/
│     ├─ src/
│     │  ╰─ myLib2.kt
│     ╰─ module.yaml
╰─ project.yaml

```

--------------------------------

### Disable JDK Provisioning and Use JAVA_HOME

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/jdk-provisioning

Force the build to use the JDK specified by JAVA_HOME and disable auto-provisioning. This is useful for controlling exact JDK versions.

```yaml
settings:
  jvm:
    jdk:
      selectionMode: javaHome

```

--------------------------------

### Enable Maven Plugin Goal in module.yaml (Shorthand)

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/maven-plugins

Enable a Maven plugin goal in the relevant `module.yaml` using the `pluginArtifactId.goalName: enabled` shortcut.

```yaml
product: jvm/app

mavenPlugins:
  maven-surefire-plugin.test: enabled
```

--------------------------------

### Configure Protobuf Maven Plugin for Source Generation

Source: https://kotlin-toolchain.org/0.11/user-guide/advanced/maven-plugins

Configure the protobuf Maven plugin in `module.yaml` to enable source generation, specifying parameters like `protocVersion`, `sourceDirectories`, and `kotlinEnabled`.

```yaml
product: jvm/app

dependencies:
  - com.google.protobuf:protobuf-kotlin:4.33.0

mavenPlugins:
  protobuf-maven-plugin.generate:
    enabled: true
    configuration:
      protocVersion: 4.33.0
      sourceDirectories: [ ./src ]
      kotlinEnabled: true
```

--------------------------------

### Project Configuration for Multi-Module Project

Source: https://kotlin-toolchain.org/0.11/user-guide/basics

Defines the list of modules included in a multi-module project. Each entry points to a module's directory.

```yaml
modules:
  - ./app
  - ./libs/lib1 
  - ./libs/lib2

```

--------------------------------

### Configure plugin tasks and generated sources

Source: https://kotlin-toolchain.org/0.11/user-guide/plugins/quick-start

Defines the task action and registers the output directory as a source for Kotlin compilation.

```yaml
tasks:
  generate:
    action: !com.example.generateSources
      propertiesFile: ${module.rootDir}/config.properties
      generatedSourceDir: ${taskOutputDir}

generated:
  sources:
    - language: kotlin 
      directory: ${tasks.generate.action.generatedSourceDir}
```

--------------------------------

### Configure All-Open Plugin with Spring Preset

Source: https://kotlin-toolchain.org/0.11/reference/module

Enables the Kotlin all-open compiler plugin and applies the 'spring' preset for automatic 'open' keyword generation.

```yaml
settings:
  kotlin:
    allOpen:
      enabled: true
      presets: [ spring ]

```

--------------------------------

### Enable Kotlin Serialization with Specific Version and Multiple Formats

Source: https://kotlin-toolchain.org/0.11/reference/module

Enables Kotlin Serialization with a specific version and includes dependencies for multiple serialization formats.

```yaml
settings:
  kotlin:
    serialization:
      enabled: true
      version: 1.9.0

dependencies:
  - $kotlin.serialization.json
  - $kotlin.serialization.protobuf

```

--------------------------------

### Project Catalog Definition (libs.versions.toml)

Source: https://kotlin-toolchain.org/0.11/user-guide/dependencies

Define library versions and coordinates in a TOML file for a single project catalog. This avoids repeating library details across modules.

```toml
[versions]
ktor = "3.3.2"

[libraries]
ktor-client-auth = { module = "io.ktor:ktor-client-auth", version.ref = "ktor" }
ktor-client-cio = { module = "io.ktor:ktor-client-cio", version.ref = "ktor" }
ktor-client-contentNegotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }

```
Tokens:
Raw