Configuration

SKIE has various configuration areas, primarily focused on which features to apply and where. SKIE has a default configuration that we consider reasonable for most projects, and we recommend using these defaults for new projects. However, modifying some of the defaults for existing projects might be beneficial - it can simplify your migration process.

tip

You can read more about migrating existing projects in the migration documentation.

Overview

There are two main ways to configure SKIE:

• "global" Gradle configuration
• "local" configuration that uses Kotlin annotations

This page describes the general concepts of SKIE configuration, and the individual configuration options are described in the subpages.

Gradle Configuration

The Skie Gradle plugin defines a skie extension that can be accessed in the build Gradle file where SKIE is applied.

A typical configuration use case is to enable or disable some features globally. For example, this config will disable the Flow interop in the whole project:

build.gradle.kts

import co.touchlab.skie.configuration.FlowInterop

skie {
    features {
        group {
            FlowInterop.Enabled(false)
        }
    }
}

info

In the example above, you can still enable Flows using annotations in the source code. Think about this global configuration as a specification of the default behavior, which can then be selectively overridden.

Selective Configuration

The Gradle configuration can be applied more selectively. The group block takes an optional string argument, which matches a prefix of the fully qualified name of declarations like classes or functions. This prefix can be, for example, used to specify a package or a class.

Let's say you want to disable Flows only in the co.touchlab.skie.types package. In that case, you can write the following:

build.gradle.kts

import co.touchlab.skie.configuration.FlowInterop

skie {
    features {
        group("co.touchlab.skie.types") {
            FlowInterop.Enabled(false)
        }
    }
}

But what if you want to disable Flows everywhere except for the co.touchlab.skie.types package? In that case, you can use multiple groups to override the configuration selectively:

build.gradle.kts

import co.touchlab.skie.configuration.FlowInterop

skie {
    features {
        group {
            FlowInterop.Enabled(false)
        }
        group("co.touchlab.skie.types") {
            FlowInterop.Enabled(true)
        }
    }
}

Note that the ordering of the groups is important. The rule is that the last matching occurrence of a given configuration is used (from all groups that match the declaration).

info

When using a group that is supposed to match a specific class, do not forget to use the fully qualified name (which includes the package name). Note that there is currently no way to select only a single class because the matching works on a prefix basis. Therefore, the group will match all nested and other classes with the same prefix. As a workaround, you can use an additional group block to revert the configuration for the unintentionally matched classes.

Annotation Configuration

Annotation configuration allows you to configure SKIE directly in the source code by adding annotations to your declarations. The most common use case is to selectively override the defaults provided by SKIE or your custom Gradle configuration.

One limitation of the annotation configuration is that annotations can be easily used only in code you can change. However, SKIE processes all declarations exported to the Objective-C, including dependencies - so those have to be configured using the Gradle configuration.

Some examples of using annotations:

Kotlin

import co.touchlab.skie.configuration.annotations.FlowInterop

@FlowInterop.Enabled
fun enabledFlow(): Flow<Int> = flowOf(1)

@FlowInterop.Disabled
fun disabledFlow(): Flow<Int> = flowOf(1)

Adding the Annotation dependency

Before you can use the SKIE annotations, you'll need to add the following dependency to all modules in which you want to use them:

build.gradle.kts

val commonMain by sourceSets.getting {
    dependencies {
        implementation("co.touchlab.skie:configuration-annotations:0.6.4")
    }
}

note

You will likely want to add the dependency to the commonMain source set, but it depends on your exact use case.

Combining the Gradle and Annotation Configuration

By default, the annotations always override the Gradle configuration. However, you can change this behavior for specific groups by setting the overridesAnnotations parameter to true, like so:

build.gradle.kts

import co.touchlab.skie.configuration.FlowInterop

skie {
    features {
        group("co.touchlab.skie.types", overridesAnnotations = true) {
            FlowInterop.Enabled(false)
        }
    }
}

In this example, the Flow interop will be disabled in the whole package co.touchlab.skie.types, even if some of its declarations have the @FlowInterop.Enabled annotation.

Disabling entire SKIE

In some cases, you might want to disable the entire SKIE compiler plugin without removing the Gradle plugin and the associated configuration. To do so, you can use the following Gradle config:

build.gradle.kts

skie {
    isEnabled.set(false)
}

tip

This can be useful, for example, during debugging or evaluating differences between using and not using SKIE.