Kotlin Toolchain

https://kotlin-toolchain.org/latest/user-guide/
Admin
The Kotlin Toolchain user guide provides comprehensive documentation covering its concepts,...
Tokens:52,976
Snippets:830
Trust Score:2.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Distribution Interface Example

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/topics/tasks?q=

Example of a configurable interface that requires path parameters to be annotated with input/output markers.

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

```

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

### Project Structure Example

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

Defines the directory layout for the project and its modules, including the plugin module.

```yaml
<root>/
├─ app/
│  ╰─ module.yaml
├─ build-config/
│  ├─ src/
│  ├─ module.yaml
│  ╰─ plugin.yaml
├─ utils/
│  ╰─ module.yaml
├─ ... 
╰─ project.yaml

```

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

### Project Structure with Proguard Rules

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

Example project structure including a proguard-rules.pro file for custom R8 rules.

```yaml
├─ src/ 
├─ test/ 
├─ proguard-rules.pro
╰─ module.yaml
```

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

### Multiplatform Settings Configuration

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Example of configuring multiplatform settings, including platform-specific settings, for a KMP library.

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

settings:
```

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

### YAML List of Strings Example

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

Illustrates how to define a list of string values in YAML.

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

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

### YAML String Examples

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

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

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

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

### Project Structure Example

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/quick-start?q=

Defines the directory structure for a Kotlin Toolchain project including modules and plugins.

```yaml
<root/>
├─ app/
│  ╰─ module.yaml
├─ build-config/
│  ├─ src/
│  ├─ module.yaml
│  ╰─ plugin.yaml
├─ utils/
│  ╰─ module.yaml
├─ ... 
╰─ project.yaml
```

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

### Kotlin/Native Module Layout Example

Source: https://kotlin-toolchain.org/latest/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

```

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

### Define Plugin Settings

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

Example of how plugin settings are declared and referenced within the plugin configuration.

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

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

### YAML Mapping Example

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

Shows how to define a mapping (key-value pairs) in YAML, including nested fields.

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

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

### Dependency Propagation Rules Example

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Demonstrates dependency propagation rules in a multiplatform project with specific platform configurations for iOS.

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

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

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

### YAML List of Mappings Example

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

Demonstrates how to define a list containing mappings in YAML, including anonymous and named mappings.

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

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

### Kotlin Distribution Interface Example

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

Shows the definition of a Distribution interface, which includes Path parameters. Any parameter using this interface or similar ones that reference files must be annotated with @Input or @Output.

```kotlin
import org.gradle.api.tasks.Input
import org.gradle.api.tasks.Output
import org.gradle.api.Configurable
import java.nio.file.Path

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

@TaskAction
fun deployDistribution(
    @Input distribution: Distribution
) {
    // Logic to deploy using distribution.manifestPath and distribution.binaryPath
}
```

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

### Common Module Template Example

Source: https://kotlin-toolchain.org/latest/user-guide/templates?q=

A template file defining common test dependencies and Kotlin language version settings.

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

settings:
  kotlin:
    languageVersion: 1.8

```

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

### Effective Dependencies for Android (Propagation Example)

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Shows the effective dependencies for Android based on propagation rules, including a local dependency.

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

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

### Multiplatform Module Directory Structure Example

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Illustrates a typical multiplatform module layout with platform-specific directories for resources and source code, using the `@platform` qualifier. This structure allows for targeted compilation and resource inclusion.

```plaintext
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

```

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

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

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Lists effective dependencies for iOS Simulator Arm64, including shared and platform-specific local dependencies.

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

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

### Configuring Plugin Settings in module.yaml

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/quick-start?q=

Example of how to configure plugin settings in an application's `module.yaml` file. This allows users to customize plugin behavior by providing values for defined settings.

```yaml
plugins:
  build-config:
    enabled: true 
    propertiesFileName: "konfig" 
    additionalConfig:
      VERSION: "1.0"

```

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

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

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Displays effective dependencies for iOS Arm64, including shared, iOS-specific, and iOS Arm64-specific local dependencies.

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

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

### Configure Metro Compiler Plugin

Source: https://kotlin-toolchain.org/latest/user-guide/advanced/kotlin-compiler-plugins?q=

Example configuration for integrating the Metro compiler plugin. This includes specifying options like 'enabled' and 'debug'.

```yaml
settings:
  kotlin:
    compilerPlugins:
      - id: dev.zacsweers.metro.compiler
        dependency: dev.zacsweers.metro:compiler:0.11.4
        options:
          enabled: true
          debug: false

```

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

### Custom Parcelize Annotation Setup (Common Code)

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

Define custom annotations and interfaces in common code for cross-platform Parcelable support.

```kotlin
@Target(AnnotationTarget.CLASS)
@Retention(AnnotationRetention.BINARY)
annotation class MyParcelize

expect interface MyParcelable
```

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

### Power Assert Example

Source: https://kotlin-toolchain.org/latest/user-guide/advanced/kotlin-compiler-plugins?q=

Demonstrates the enhanced assertion output provided by the Power Assert compiler plugin. It shows detailed information about variable values and expression evaluations upon assertion failure.

```kotlin
Incorrect length
assert(hello.length == world.substring(1, 4).length) { "Incorrect length" }
       |     |      |  |     |               |
       |     |      |  |     |               3
       |     |      |  |     |               orl
       |     |      |  |     world!
       |     |      |  false
       |     5
       Hello

```

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

### Add KmLogging Library to KMP Project

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Example of adding the KmLogging library to a multiplatform project targeting Android, iOS Arm64, and JVM.

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

dependencies:
  - com.diamondedge:logging:2.1.0
```

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

### Platform-Specific Test Configuration

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

Example of a multiplatform library (`kmp/lib`) with platform-specific test configurations. Test settings and dependencies can be inherited or overridden per platform, as shown with `test@ios/`.

```yaml
├─ src/
├─ src@ios/
├─ test/           # Sees declarations from src/. Executed on all platforms.
│  ├─ MainTest.kt
│  ╰─ ...
├─ test@ios/       # Sees declarations from src/, src@ios/, and `test/`. Executed on iOS platforms only.
│  ├─ IOSTest.kt
│  ╰─ ...
╰─ module.yaml

```

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

### Configure Koin Compiler Plugin

Source: https://kotlin-toolchain.org/latest/user-guide/advanced/kotlin-compiler-plugins?q=

Example configuration for integrating the Koin compiler plugin. The plugin ID is typically found in the plugin's CommandLineInterface implementation.

```yaml
settings:
  kotlin:
    compilerPlugins:
      - id: io.insert-koin.compiler.plugin
        dependency: io.insert-koin:koin-compiler-plugin:0.3.0

```

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

### Customize Generated Content with Fragment Clause

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/topics/tasks?q=

This example demonstrates customizing generated content by specifying a 'fragment' with 'isTest' and 'modifier' properties. This allows generated sources to be treated as test sources for a specific platform (e.g., 'ios'). It also shows how to declare a generated cinterop definition file.

```yaml
generated:
  sources:
    - language: kotlin
      directory: ${tasks.generate.action.generatedSourceDir}
      fragment:
        isTest: true
        modifier: ios

  cinteropDefinitions:
    - defFile: ${tasks.provideNativeLibs.action.generatedDefFile}
      fragment: native

```

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

### Global Reference Properties Example

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

These properties are available in the root scope and provide information about the module, project, and plugin settings. Use them to access configuration details like module names or project root paths.

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

tasks:
  myTask: {...}

```

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

### Effective Settings for iOS Simulator Arm64 Platform

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Presents the effective settings for the `iosSimulatorArm64` platform, demonstrating the merging of Kotlin toolchain configurations from multiple specialization levels.

```yaml
settings@iosSimulatorArm64:
  kotlin:
    languageVersion: 1.9
    freeCompilerArgs: [x, y, z]
```

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

### Use Toolchain Catalog Dependencies

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

Demonstrates referencing dependencies from implicit toolchain catalogs like Kotlin and Compose.

```yaml
dependencies:
  - $kotlin.reflect      # dependency from the Kotlin catalog
  - $compose.material3   # dependency from the Compose Multiplatform catalog
```

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

### Library Catalog Definition

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

Example of a library catalog definition in TOML format, specifying a library without its version.

```toml
[libraries]
ktor-client-core = "io.ktor:ktor-client-core"

```

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

### Custom Parcelize Annotation Setup

Source: https://kotlin-toolchain.org/latest/user-guide/product-types/android-app?q=

Configures the Kotlin Toolchain to recognize a custom Parcelize annotation for cross-platform compatibility.

```yaml
settings:
  kotlin:
    # for the expect/actual MyParcelable interface
    freeCompilerArgs: [ -Xexpect-actual-classes ]
  android:
    parcelize:
      enabled: true
      additionalAnnotations: [ com.example.MyParcelize ]
```

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

### Directory Structure for Multiplatform Projects

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Illustrates the directory structure for a Kotlin Multiplatform project, showing how source sets are organized and inherit declarations.

```text
├─ src/
├─ src@jvmAndAndroid/ # sees declarations from src/
├─ src@jvm/           # sees declarations from src/ and src@jvmAndAndroid/
╰─ src@android/       # sees declarations from src/ and src@jvmAndAndroid/
```

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

### Custom Entry Point Configuration

Source: https://kotlin-toolchain.org/latest/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' function.

```yaml
product: linux/app

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

```

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

### Platform-Specific Settings Specialization

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Illustrates how to define common settings and then specialize them for different platforms like Android and iOS using `@platform` qualifiers.

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

settings:
  kotlin:
    languageVersion: 1.8
    freeCompilerArgs: [x]
  android:
    compileSdk: 33

settings@android:
  compose: enabled

settings@ios:
  kotlin:
    languageVersion: 1.9
    freeCompilerArgs: [y]

settings@iosArm64:
  kotlin:
    freeCompilerArgs: [z]
```

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

### Configure Metro Compiler Plugin

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

Example configuration for the Metro compiler plugin. The plugin ID is found in the CommandLineInterface implementation of the compiler plugin.

```yaml
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

```

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

### Requesting Classpath with Classpath

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

Use `Classpath` to get a resolved classpath. It supports convenience references like `module.runtimeClasspath` or ad-hoc dependency resolution.

```kotlin
@TaskAction
fun packageClasspath(
    @Input appClasspath: Classpath,
    @Input extraClasspath: Classpath?,
) {
    appClasspath.resolvedFiles.forEach {  it.copyTo(...) }
    ...
}

```

```yaml
tasks:
  package:
    action: !packageTheApp
      appClasspath: ${module.runtimeClasspath} 
      extraClasspath: 
        - foo:bar:1.0
        - ${pluginSettings.extraDependency}

```

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

### Project Configuration (project.yaml)

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

Configures the project by listing its modules and registering the custom plugin.

```yaml
modules:
  - app   
  - build-config 
  - utils 
  - ...   

plugins: 
  - ./build-config

```

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

### Example of Lexical Scope Definition

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

Illustrates how lexical scopes are defined in YAML mappings, including implicit properties like defaults and reference-only properties.

```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: 

```

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

### Publishing Command

Source: https://kotlin-toolchain.org/latest/user-guide/publishing?q=

Execute this command to publish all modules that have publishing enabled and configured repositories.

```bash
kotlin publish someIdOfYourChoosing

```

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

### Declare Local Module Dependencies

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

Specify dependencies on other modules within your project using relative paths. Paths must start with `./` or `../`.

```yaml
product: jvm/app

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

```

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

### Cyclic Dependency Example in Kotlin Toolchain

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/quick-start?q=

Illustrates a cyclic dependency scenario where a plugin cannot generate resources for itself due to task dependencies. This is detected by the build system.

```text
1. task `generateSources` in module `my-plugin` from plugin `my-plugin` (*)
   ╰───> depends on the compilation of its source code
2. compilation of module `my-plugin` <───────────────╯
   ╰───> needs sources from ──────────────────╮
3. source generation for module `my-plugin` <─╯
   ╰───> includes the directory `<project-build-dir>/tasks/_my-plugin_generateSources@my-plugin` generated by
4. task `generateSources` in module `my-plugin` from plugin `my-plugin` (*) <───────────────────────────────╯


```

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

### Enable Kotlinx RPC Support

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

Add this configuration to your `module.yaml` file to enable kotlinx.rpc support, including code generation and BOM application.

```yaml
settings:
  kotlin:
    rpc: enabled

```

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

### Task-Scoped Reference Properties Example

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

These properties are available within the lexical scope of each task, such as the unique output directory for a given task. They are useful for task-specific configurations.

```yaml
tasks:
  myTask:
    # taskOutputDir
    action: {...}

```

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

### Enable Ktor Support

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

Add this to `module.yaml` to enable Ktor. This applies the Ktor BOM, adds Ktor entries to the library catalog, and sets `io.ktor.development=true` when running with `kotlin run`.

```yaml
settings:
  ktor: enabled

```

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

### Project Configuration (project.yaml)

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/quick-start?q=

Configures the project modules and registers the build-config plugin.

```yaml
modules:
  - app   
  - build-config 
  - utils 
  - ...   

plugins: 
  - ./build-config
```

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

### Declare Module and Maven Dependencies

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

Declare local module paths, Maven coordinates, and variables in the `dependencies` list. Ensure paths start with `./` or `../` for local modules.

```yaml
dependencies:
  - ./my-other-module 
  - org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.1 
  - $libs.apache.commons.lang3 
  - $kotlin.reflect 

```

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

### Enable Plugin with Custom Configuration

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/topics/structure?q=

Enable a plugin and provide specific configuration settings by defining its ID as an object in the `plugins` section of the `module.yaml` file. Set `enabled: true` and add other necessary options.

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

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

### Enable Spring Boot Support

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

Add this to `module.yaml` to enable basic Spring Boot integration. This applies the Spring Boot Dependencies BOM, adds starter dependencies, configures Kotlin compiler plugins, and sets necessary compiler arguments for Java and Kotlin.

```yaml
settings:
  springBoot: enabled

```

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

### Customize Keystore Properties File Path

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

Customize the path to the keystore.properties file used for signing.

```yaml
settings:
  android:
    signing:
      enabled: true
      propertiesFile: ./keystore.properties # default value
```

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

### Credentials File for Publishing

Source: https://kotlin-toolchain.org/latest/user-guide/publishing?q=

Create a properties file to store your publishing credentials, including username and password.

```properties
username=adele
password=imRollingInTheDeep

```

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

### Source Directory Structure for Joint Compilation

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

Example of a source directory structure that supports joint compilation between Java and Kotlin for JVM/Android targets. It shows how code can be organized in platform-specific source sets.

```treeview
├─ src/ 
│  ├─ main.kt
├─ src@jvm/ 
│  ├─ KotlinCode.kt
│  ├─ JavaCode.java
├─ src@android/ 
│  ├─ KotlinCode.kt
│  ├─ JavaCode.java
├─ src@ios/ 
│  ╰─ ...
╰─ module.yaml
```

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

### Run Custom Command for Specific Modules

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

To run a custom command on only certain modules, use the '--module' option, which can be repeated. This example shows running 'updateDetektBaseline' for 'api' and 'core' modules.

```bash
$ ./kotlin do updateDetektBaseline --module api --module core  # Will update baseline only for the 'api' and 'core' modules
# or
$ ./kotlin do updateDetektBaseline -m api -m core
```

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

### Complex Multiplatform Settings with Qualifiers

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

Demonstrates a comprehensive configuration for a Kotlin Multiplatform project, including common settings and specialized settings for Android and various iOS architectures using `@platform`-qualifiers. This highlights how settings propagate and merge.

```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]
```

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

### Define Configurable Kotlin Interfaces

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

Example of defining two configurable interfaces, `MySettings` and `Nested`, along with an enum `MyEnum`. Note the restrictions: no methods, superinterfaces, or generics; only read-only properties of configurable types; default getters are allowed.

```kotlin
@Configurable
interface MySettings {
    /**
    * Note: KDocs on configurable entities are visible to the tooling
    */
    val booleanSetting: Boolean
    val intSetting: Int
    val stringSetting: String
    val nested: Nested
    val pathSetting: Path
    val mapSetting: Map<String, String>
    val listSetting: List<Nested>
}

@Configurable
interface Nested {
    val enumSetting: MyEnum
    val nullableStringSetting: String?
}

enum class MyEnum { Hello, Bye }

```

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

### Configure JVM Application Entry Point

Source: https://kotlin-toolchain.org/latest/user-guide/product-types/jvm-app

Override the default entry point by specifying the main class in the module settings. This is useful when the main function is not in the default 'src/main.kt' location.

```yaml
product: jvm/app

settings:
  jvm:
    mainClass: org.example.myapp.MyMainKt

```

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

### Define Configurable Interface in Kotlin

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/topics/configuration?q=

Example of a valid Kotlin interface annotated with `@Configurable`. It demonstrates allowed property types like Boolean, Int, String, nested configurable interfaces, Maps, and Lists. KDocs on configurable entities are visible to tooling.

```kotlin
import java.nio.file.Path

@Configurable
interface MySettings {
    /**
    * Note: KDocs on configurable entities are visible to the tooling
    */
    val booleanSetting: Boolean
    val intSetting: Int
    val stringSetting: String
    val nested: Nested
    val pathSetting: Path
    val mapSetting: Map<String, String>
    val listSetting: List<Nested>
}

@Configurable
interface Nested {
    val enumSetting: MyEnum
    val nullableStringSetting: String?
}

enum class MyEnum { Hello, Bye }
```

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

### Run a Custom Command

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

Execute a custom command using the 'do' command followed by the command name. To see available commands, run './kotlin show commands'.

```bash
$ ./kotlin do updateDetektBaseline
```

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

### Maven-like Module Directory Structure

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

Illustrates the standard directory organization for a module using the Maven-like layout, including main sources, test sources, and resources.

```directory
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

```

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

### Multi-Module Project Layout

Source: https://kotlin-toolchain.org/latest/user-guide/basics?q=

For multi-module projects, `project.yaml` lists all modules. Each module has its own `module.yaml` defining its product type and dependencies.

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

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

```yaml
product: jvm/app

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

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

### Simplified Configuration after Addressing Ambiguity

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Presents a more readable configuration format where platform-specific settings are directly under the main settings block, simplifying the structure.

```yaml
product: android/app

settings:
  android:
    compileSdk: 33
  kotlin:
    languageVersion: 1.8
```

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

### Use Project Catalog Dependencies

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

Lists dependencies to be included from the project catalog in a module's configuration.

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

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

### Configure JDK Version and Distributions

Source: https://kotlin-toolchain.org/latest/user-guide/advanced/jdk-provisioning?q=

Specify the major JDK version and an optional allowlist of distributions. The build will fail if a matching JDK cannot be provisioned.

```yaml
settings:
  jvm:
    jdk:
      version: 21  # major JDK version
      distributions: [temurin, zulu]  # optional allowlist of distributions (accept all if omitted)

```

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

### Swift Entry Point for iOS App

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

Defines the expected structure for the entry point of an iOS application, which must be a `@main` struct in a Swift file within the `src` folder.

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

```

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

### Define Project Library Catalog

Source: https://kotlin-toolchain.org/latest/user-guide/dependencies?q=

Define versions and library coordinates in a TOML file for reuse across modules. Use `version.ref` to reference versions defined in the `[versions]` section.

```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" }

```

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

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

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

Configuration snippet to add to `module.yaml` to activate the Maven-like module layout for the Kotlin Toolchain.

```yaml
layout: maven-like

```

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

### Configure Protobuf Maven Plugin for Source Generation

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

Integrate the protobuf-maven-plugin to automatically generate Kotlin sources from .proto files. Ensure the plugin is listed and configured with necessary parameters like protocVersion and sourceDirectories.

```yaml
modules:
  - app

mavenPlugins:
  - io.github.ascopes:protobuf-maven-plugin:2.12.0

```

```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

```

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

### Execute a Plugin Task Manually

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/quick-start?q=

Demonstrates how to manually execute a specific plugin task from the command line. This is useful for tasks that do not have declared outputs and are not automatically triggered.

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

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

### Project Structure for Testing

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

Standard project layout with separate directories for production and test code. The `test/` folder contains test files, and `module.yaml` defines project configuration.

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

```

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

### Map Plugin Settings to Task Parameters

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

Declare task actions in plugin.yaml and map plugin settings to task parameters using `${...}` expressions. This links user-configurable settings to the task's input and output.

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

```

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

### Define Product Platforms for KMP Library

Source: https://kotlin-toolchain.org/latest/user-guide/multiplatform?q=

Specify the target platforms for a Kotlin Multiplatform library using the `product.platforms` list. Only platform names are allowed, not family names, to ensure stability across Kotlin versions.

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

```

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

### Use Project Catalog Dependencies in Module

Source: https://kotlin-toolchain.org/latest/user-guide/dependencies?q=

Reference dependencies defined in the project catalog using the `$libs.<key>` syntax within your module's dependency list.

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

```

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

### Enable Compose for JVM Desktop App

Source: https://kotlin-toolchain.org/latest/user-guide/builtin-tech/compose-multiplatform

Enables Compose for a JVM application. Requires the `$compose.desktop.currentOs` dependency from the built-in catalog.

```gradle
product: jvm/app

dependencies:
  - $compose.desktop.currentOs 

settings: 
  compose: enabled 


```

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

### Enable All-open Plugin with Presets

Source: https://kotlin-toolchain.org/latest/user-guide/advanced/kotlin-compiler-plugins?q=

Enable the All-open compiler plugin using predefined presets for common frameworks like Spring and Micronaut. This simplifies configuration by including relevant annotations.

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

```

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

### Provide Publishing Credentials

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

A properties file containing the username and password for authenticating with the Maven repository.

```properties
username=adele
password=imRollingInTheDeep


```

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

### Using BOM with Library Catalog

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

Demonstrates how to reference a library from a catalog when its version is managed by an imported BOM. The version can be omitted in the module definition if the BOM provides it.

```yaml
dependencies:
  - bom: io.ktor:ktor-bom:3.2.0
  - $libs.ktor.client.core

```

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

### Configure JDK Distributions with Fallback

Source: https://kotlin-toolchain.org/latest/user-guide/advanced/jdk-provisioning?q=

Allows specifying multiple JDK distributions, providing fallbacks if a preferred distribution is not available on a specific platform.

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

```

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

### Configure JDK Version and Distributions

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

Specify the major JDK version and an optional allowlist of distributions. If distributions are omitted, all are accepted.

```yaml
settings:
  jvm:
    jdk:
      version: 21
      distributions: [temurin, zulu]

```

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

### Create config.properties File

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/quick-start?q=

Defines configuration properties for the generateSources task. This file is expected by the task and should contain necessary key-value pairs.

```properties
APP_NAME=My Cool App
```

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

### Wiring Plugin Settings to Task in Kotlin

Source: https://kotlin-toolchain.org/latest/user-guide/plugins/quick-start?q=

Demonstrates how to access and use plugin settings within a Kotlin task. The `@Input` and `additionalConfig` parameters are used to pass configuration values to the task.

```kotlin
// ...
@TaskAction
fun generateSources(
  @Input propertiesFile: Path,
  @Output generatedSourceDir: Path,
  additionalConfig: Map<String, String>, 
) {
  // ...
  // don't forget to process properties passed via the additionalConfig parameter
  // ...  
}


```
Tokens:
Raw