### Example Usage of Kotlin Wrapper Script

Source: https://kotlin-toolchain.org/latest/cli/provisioning?q=

Run Kotlin CLI commands using the wrapper script. No installation is needed for users cloning the project.

```bash
./kotlin build
```

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

### Install Kotlin CLI via SDKMAN

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

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

```bash
sdk install kotlintoolchain

```

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

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

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

Installs the Kotlin CLI wrapper using a PowerShell command on Windows. It uses `ExecutionPolicy ByPass` to allow script execution.

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

```

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

### Install Kotlin CLI on Linux/macOS

Source: https://kotlin-toolchain.org/latest/getting-started/migrating-from-maven?q=

Installs the Kotlin Command Line Interface using a script for Linux and macOS systems.

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

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

### Install Kotlin CLI on Windows

Source: https://kotlin-toolchain.org/latest/getting-started/migrating-from-maven?q=

Installs the Kotlin Command Line Interface using PowerShell for Windows systems. Ensure your execution policy allows script execution.

```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/latest/cli

Installs the Kotlin CLI wrapper using a curl command on Linux and macOS. It places the wrapper in `~/.local/bin` and updates the shell profile.

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

```

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

### Project Structure Example

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

Defines the basic directory layout for a Kotlin Toolchain plugin project.

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

```

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

### Project Structure Example

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

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

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

### YAML Mapping Example

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

Illustrates a basic YAML mapping with nested key-value pairs.

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

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

### YAML String Examples

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

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

### YAML List of Mappings Example

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

Demonstrates a YAML sequence containing nested mappings.

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

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

### YAML List of Strings Example

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

Shows how to define a YAML sequence (list) of string values.

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

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

### Create a Basic Compose Desktop Application

Source: https://kotlin-toolchain.org/latest/getting-started/tutorial?q=

Implement a simple GUI application using Compose Multiplatform. This example displays a 'Hello, World!' text in a window.

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

```

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

### Dependency Propagation Example

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

Demonstrates how dependencies declared in general and platform-specific sections propagate to effective dependency lists based on propagation rules.

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

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

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

### Test Directory Inheritance Example

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

Visualizes the directory structure for a multiplatform project, highlighting how test directories inherit configurations from source directories.

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

```

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

### Global Reference Properties Example

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

Illustrates the structure for defining tasks and accessing global reference properties like module name and root directory.

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

tasks:
  myTask: {...}

```

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

### Global Reference-Only Properties Example

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

Illustrates the structure for referencing global properties like module and plugin settings within a plugin configuration.

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

tasks:
  myTask: {...}


```

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

### Toolchain Settings Configuration

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

Example of the settings section in a module file, configuring Kotlin language version and Android compile SDK.

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

```

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

### Complex Platform Specialization Example

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

Illustrates advanced use of '@platform' qualifiers for specializing settings across common, platform, and specific platform levels.

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

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

### Multiplatform Module Directory Layout

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

An example of a multiplatform module's directory structure, showing how common and platform-specific resources and source files are organized.

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

```

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

### Define Distribution Interface

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

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
}

```

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

### Task-Scoped Reference Properties Example

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

Shows how task-scoped properties, such as the task output directory, can be accessed within a task's configuration.

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

```

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

### Platform-Specific Test Configuration

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

Provides an example of a multiplatform library configuration, showing how test dependencies and settings can be platform-specific or overridden for tests.

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

```

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

### Configure Maven-like Layout for JVM App

Source: https://kotlin-toolchain.org/latest/reference/module?q=

Example of setting a 'maven-like' layout for a JVM application module. This layout is only supported for 'jvm/app' or 'jvm/lib' product types.

```kotlin
product: jvm/app

layout: maven-like

settings:
  # ...

```

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

### Swift Entry Point for iOS App

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

Example of a Swift entry point for an iOS application, marked with the @main attribute. This struct serves as the application's entry point.

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

```

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

### 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 plugin, showing variable values and expression evaluations upon failure.

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

```

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

### Task-Scoped Reference-Only Properties Example

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

Shows how task-scoped properties, such as the task output directory, can be referenced within a task's configuration.

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


```

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

### Common Module Template Example

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

A template file defining common test dependencies and Kotlin language version settings. Template files cannot contain the `product:` section.

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

settings:
  kotlin:
    languageVersion: 1.8

```

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

### KMP Library Module Configuration

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

Example of a module.yaml file for a Kotlin Multiplatform (KMP) library. It defines product type, platforms, and platform-specific dependencies.

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

```

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

### Configure Test Dependencies in module.yaml

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

Add test-specific dependencies using the `test-dependencies` section in `module.yaml`. This example adds the MockK library for mocking.

```yaml
product: jvm/app

dependencies:
  - org.jetbrains.kotlinx:kotlinx-datetime:0.6.2

test-dependencies:
  - io.mockk:mockk:1.13.10
```

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

### Configure Protobuf Maven Plugin for Source Generation

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

Example configuration for the protobuf-maven-plugin to enable Kotlin source generation. Ensure the protobuf-kotlin dependency is also included.

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

```

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

### JVM Application Module Configuration

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

Example of a module.yaml file for a JVM application. It specifies the product type, dependencies, and Kotlin compiler settings.

```yaml
product: jvm/app 

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

settings: 
  kotlin:
    version: 2.2.21 
    allWarningsAsErrors: true 

```

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

### Shorthand Notation Example

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

Demonstrates the shorthand notation for constructing objects, where a property marked with @Shorthand allows construction from a single value instead of a full mapping. This is useful for properties like 'dependencies'.

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

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

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

### Add Test Code

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

Add test code to the `test/` folder. This example demonstrates a simple test case using Kotlin's testing framework.

```kotlin
import kotlin.test.*

class MyTest {
    @Test
    fun doTest() {
        assertTrue(true)
    }
}
```

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

### Shorthand Notation Example

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

Illustrates the shorthand notation for constructing objects, where a property marked with @Shorthand allows construction from a value instead of a mapping. This is a concise way to set dependencies.

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

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

### Configure Maven Plugin with Raw XML for PlexusConfiguration

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

For configuration parameters with `PlexusConfiguration` type, pass raw XML within the `configuration` block. This example enforces a minimum Java version.

```yaml
product: jvm/app

mavenPlugins:
  maven-enforcer-plugin.enforce:
    enabled: true
    configuration:
      rules: "
        <rules>
          <requireJavaVersion>
            <version>[21,)</version>
          </requireJavaVersion>
        </rules>"
```

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

### Project Structure (Initial)

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

Initial project structure after setting up basic directories.

```yaml
├─ jvm-app/
│  ├─ ...
│  ╰─ module.yaml
├─ shared/
│  ├─ ...
│  ╰─ module.yaml
├─ kotlin
├─ kotlin.bat
╰─ project.yaml

```

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

### Create a Basic Compose UI Application

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

Replace the contents of `main.kt` with this code to create a simple GUI application using Compose Multiplatform. It displays a 'Hello, World!' text.

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

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

### Explore Kotlin CLI Help

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

Displays available commands and general options for the Kotlin CLI. Use `--help` with specific commands 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

```

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

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

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

Use the expanded syntax in `module.yaml` to enable a plugin and provide specific configuration settings.

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

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

### Customize scope of JSON format dependency

Source: https://kotlin-toolchain.org/latest/user-guide/builtin-tech/kotlinx-serialization?q=

Define the dependency scope for the JSON serialization format, for example, 'compile-only'.

```yaml
settings:
  kotlin:
    serialization: enabled

dependencies:
  - $kotlin.serialization.json: compile-only
```

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

### Example of Lexical Scopes in YAML

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

Illustrates how lexical scopes are defined in a YAML structure, including default 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: 

```

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

### Annotating Composable for Hot Reload

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

Example of annotating a parameter-less Composable function with @DevelopmentEntryPoint to enable hot-reloading of that specific component.

```kotlin
@DevelopmentEntryPoint 
@Composable
fun MySuperComponent() { 
    MyComponentWithParams(title = "Dummy title", description = "Lorem ipsum dolor sit amet")
}
```

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

### Unknown Maven Plugins Configuration

Source: https://kotlin-toolchain.org/latest/getting-started/migrating-from-maven?q=

Example of how unknown Maven plugins are configured in `module.yaml`. By default, they are disabled and can be enabled selectively.

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

```

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

### Basic Kotlin 'Hello, World!' Main Function

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

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

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

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

### Multiplatform Settings with Platform Specialization

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

Illustrates common toolchain settings and their specialization for Android and iOS platforms 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]
```

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

### Declare Module Dependencies

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

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

```yaml
product: jvm/app

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

```

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

### Run Project Conversion Tool

Source: https://kotlin-toolchain.org/latest/getting-started/migrating-from-maven?q=

Executes the Kotlin Toolchain's project conversion command. This tool converts Maven projects to the Kotlin Toolchain format.

```bash
kotlin tool convert-project
```

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

### Template Conflict Example

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

Illustrates a conflict when sibling templates define different scalar values for the same property. The Kotlin Toolchain reports such conflicts.

```yaml
settings:
  jvm:
    release: 17

```

```yaml
settings:
  jvm:
    release: 21

```

```yaml
product: jvm/app

apply:
  - ./java17-compatible.module-template.yaml
  - ./java21-compatible.module-template.yaml

```

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

### Unsupported Reference in Mapping Keys

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

References are not permitted within mapping keys in plugin configuration files. This example shows an invalid construction.

```yaml
myMap:
  ${module.name}: "value"
```

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

### Maven-like Module Directory Structure

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

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

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

```

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

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

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

Use the shorthand syntax in `module.yaml` to simply enable a plugin with its default configuration.

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

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

### JVM App Main Entry Point

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

The main function for the JVM application, which displays the 'sayHello' Composable within a window.

```kotlin
import androidx.compose.ui.window.Window
import androidx.compose.ui.window.application

fun main() = application {
    Window(onCloseRequest = ::exitApplication) {
        sayHello()
    }
}


```

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

### Configure Metro Compiler Plugin

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

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

```

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

### Update project.yaml for Multiplatform Setup

Source: https://kotlin-toolchain.org/latest/getting-started/tutorial?q=

This updated project.yaml includes the new android-app and ios-app modules, in addition to the existing jvm-app and shared modules.

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

```

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

### Add Library Dependencies in module.yaml

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

Declare external library and module dependencies for the plugin. This example adds the kotlin-poet library and a local utils module.

```yaml
product: jvm/amper-plugin

dependencies:
  - com.squareup:kotlinpoet:2.2.0 
  - ../utils 

```

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

### Enable Ktor Support

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

Add this to your `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

```

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

### Run a Custom Command

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

Execute a custom command by prefixing its name with `./kotlin do`. Use `./kotlin show commands` to list available commands.

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

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

### Configure Koin Compiler Plugin

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

Example configuration for the Koin compiler plugin. The plugin ID is typically 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, 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

```

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

### Enable Compose UI Framework in module.yaml

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

Enable the Compose framework toolchain by setting `compose.enabled` to `true` and adding Compose dependencies in `module.yaml`.

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

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

### Project Configuration (Multiplatform)

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

Updated project.yaml to include Android and iOS modules.

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


```

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

### Configure Compose Multiplatform (Short Form)

Source: https://kotlin-toolchain.org/latest/reference/module?q=

Enable the Compose Multiplatform runtime and dependencies using the short form configuration.

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

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

### Configure JVM Application Entry Point

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

Specifies the main class for a JVM application when it deviates from the default 'main.kt' in the src folder.

```yaml
product: jvm/app

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

```

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

### Gradle Equivalent for Code Shrinking

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

Shows the Gradle configuration equivalent to the Kotlin Toolchain's default R8 settings for minification and resource shrinking.

```gradle
isMinifyEnabled = true
isShrinkResources = true
proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
```

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

### Template Conflict Resolution Example

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

Illustrates a conflict scenario where two sibling templates define different scalar values for the same property. The Kotlin Toolchain reports such conflicts.

```yaml
java17-compatible.module-template.yaml
settings:
  jvm:
    release: 17

```

```yaml
java21-compatible.module-template.yaml
settings:
  jvm:
    release: 21

```

```yaml
module.yaml
product: jvm/app

apply:
  - ./java17-compatible.module-template.yaml
  - ./java21-compatible.module-template.yaml

```

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

### Project Configuration (project.yaml)

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

Configures the modules and registers the custom plugin for the project.

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

plugins: 
  - ./build-config

```

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

### Define Plugin Settings

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

This snippet shows how to configure plugin settings, referencing a global property `pluginSettings` which holds the configured settings for each module.

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

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

### Cyclic Dependency Example in Kotlin Toolchain

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

Illustrates a cyclic dependency scenario where a plugin cannot generate resources for itself due to task dependencies. This is a conceptual representation of the dependency chain.

```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` (*) <───────────────────────────────╯


```

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

### Project Structure with Java and Kotlin Files

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

Illustrates how Java and Kotlin files can coexist within the same source directory in a Kotlin Toolchain project.

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

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

### Configure Metro Compiler Plugin

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

Example configuration for the Metro compiler plugin, including options like 'enabled' and 'debug'. The plugin ID is found in the CommandLineInterface implementation.

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

```

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

### Wiring Plugin Settings to Task in Kotlin

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

Shows how to receive plugin settings, such as properties file path and additional configuration map, as parameters within a Kotlin task action.

```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
  // ...  
}


```

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

### Define Custom Task and Generated Sources

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

Example of a custom task 'generate' that produces sources and declares them in the 'generated.sources' block. The 'generatedSourceDir' property is used to specify the output directory.

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

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

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

### Enable All-open Plugin with Framework Presets

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

Utilize 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

```

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

### Create an Alias for Shared Code

Source: https://kotlin-toolchain.org/latest/reference/module?q=

Use aliases to define a group of platforms that can share code, dependencies, and settings. This example creates an alias 'jvmAndAndroid' for the 'jvm' and 'android' platforms.

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

aliases:
  - jvmAndAndroid: [jvm, android]

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

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

### Selecting Target Platforms in `product.platforms`

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

Specify the target platforms for your multiplatform module using the `product.platforms` list in your configuration. Only platform names, not family names, are allowed.

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

```

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

### Add Extra Dependencies for Maven Plugin Mojo

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

Add extra dependencies required by a mojo under the `dependencies` key of the mojo configuration. This example adds a dependency for the `nohttp-checkstyle` plugin.

```yaml
product: jvm/app

mavenPlugins:
  maven-checkstyle-plugin.checkstyle:
    enabled: true
    dependencies:
      - io.spring.nohttp:nohttp-checkstyle:0.0.11
    configuration:
      configLocation: ./nohttp-checkstyle.xml
      includes: "**/*"
```

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

### Project Configuration (project.yaml)

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

Configures the project modules and registers the custom build plugin.

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

plugins:
  - ./build-config
```

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

### Configure Java Annotation Processors with Options

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

Reference a processor using a library catalog entry and pass custom options using the `processorOptions` map. For example, enabling debug mode.

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

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

### Customize Generated Content Scope with Fragments

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

Demonstrates advanced customization of generated content using the 'fragment' clause. This example shows how to specify 'isTest' and 'modifier' for generated sources and cinterop definitions.

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

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

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

### Configure Compose Multiplatform with Resources

Source: https://kotlin-toolchain.org/latest/reference/module?q=

Enable Compose Multiplatform, specify the version, and configure resource handling. This includes setting a package name for generated resources and controlling their visibility.

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

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

### Configure Java Annotation Processing with Options

Source: https://kotlin-toolchain.org/latest/reference/module?q=

Configure Java annotation processing, including specifying processors and passing custom options to them. This example uses a catalog reference for `auto-service` and enables debug output.

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

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

### Configure Java Annotation Processor Options

Source: https://kotlin-toolchain.org/latest/user-guide/advanced/java-annotation-processing?q=

Customize annotation processors by passing options using the `processorOptions` map. This example shows how to enable debug mode for an annotation processor referenced via a library catalog.

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

```

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

### Customizing Plugin Behavior in app module.yaml

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

Demonstrates how to enable and configure a plugin in an application's module.yaml file, overriding default settings like properties file name and adding extra configurations.

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


```

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

### Run a Specific Custom Command

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

Execute a predefined custom command using the 'do' command followed by the command name. Use this to perform custom build-related actions.

```bash
./kotlin do updateDetektBaseline

```