KiteConfig/io.github.yuroyami.kiteconfig/KiteConfigExtension

KiteConfigExtension

abstract class KiteConfigExtension : KiteFlowScope, KiteConfigValues

The single source of truth for your app's identity. Apply to the root project.

The law

Facts always flow. A declared fact reaches every platform found, on every build, in memory or as files under build/. Declaring it is the consent. skip() and only() beside the fact are the only flow control.
rewrite { } is the only word that acts on YOUR files. It arms a by-name task that edits source. dryRun, backups, and onConflict always apply.
One topic, one block. Platform corners nest inside topics. Platform blocks hold only platform-exclusive things.

Three lines are a complete setup:

kiteConfig {
    appName = "Jetzy"
    appId   = "com.example.jetzy"
    version = "1.4.0"
}

Locales auto-detect from Compose resources, the shared module and the app modules are detected too. Everything else below is optional.

The full surface

kiteConfig {
    appName = "Jetzy"
    appId   = "com.example.jetzy"

    jvm {
        toolchain = 21             // build with this JDK
        target = 17                // Java and Kotlin bytecode level together
    }

    version = "1.4.0"
    version {
        // scheme { v -> "..." }       // optional: your own build-number scheme
        rebuild = 0                    // re-upload the same version to a store
    }

    locales { tags = listOf("en", "ar", "fr") }  // omit to detect them

    logo {
        foreground = file("art/logo-fg.png")
        background = color("#0B0B0F")  // or image(file("art/bg.png"))
        foregroundScale = 0.75         // optional, per renderer default
    }

    splash {
        enabled = true                 // off until you say this
        dark { backgroundColor = "#000000" }
    }

    optIns {
        add("kotlinx.cinterop.ExperimentalForeignApi")
    }

    android {
        appId { suffix = ".android" }  // applicationId = appId + suffix
        version {
            rebuild = 1                        // this platform's counter
            publishedBuildNumber = "1001003090" // new numbers must beat it
        }
        locales { filterResources = true }  // drop res outside the list
        splash { theme = "AppTheme" }       // the theme the splash inherits
        sdk(min = 26, target = 36, compile = 36)
    }

    ios {
        appName = "Jetzy Lite"         // only this platform differs
        infoPlist { proMotion = true }
        // xcodeTargets("iosApp")      // only with several app targets
    }

    desktop {
        appId { suffix = ".desktop" }
        linuxPackageName = "jetzy"
    }

    web { ioWorker { targets("js") } }

    buildConfig {                      // presence generates into build/
        packageName = "com.example.jetzy"
        stringField("API_HOST", "api.jetzy.app")
    }

    modules { shared = ":shared" }     // only when detection guesses wrong

    autoApply = true                   // ordinary builds apply the changes
    dryRun  = false
    backups = true
    // ignoreVersionGuards = true  // off the tested AGP/KGP/Compose matrix, on your own head
}

What you can inject where

You can inject	Works in	Meaning
`skip(p...)` / `only(p...)`	root, `version`, `locales`, `logo`, `splash`	flow control, at root = platform master
`appName` / `appId`	`android`, `ios`, `desktop`	that platform's own value
`appId { suffix }`	`android`, `ios`, `desktop`	appended to the shared `appId`
`android { }` / `ios { }` / `desktop { }` corner	`version`, `logo`	platform detail scope
`version` / `version { }`	`android`, `ios`, `desktop`	that platform's version and numbering
`rebuild`, `buildNumber`, `publishedBuildNumber`	`version` in a platform block	counter, exact number, guard floor
`dark { }`	`splash`	dark-mode variant
typed `*Field(...)`	`buildConfig`	generated constants

Tasks

kiteCheck, kiteDoctor, kiteVerify, and kitePlan are read-only and always safe. kiteApply applies the configured source changes for every selected platform; kiteApplyAndroid and kiteApplyIos apply one. With autoApply = true an ordinary build runs the plan for the platform it is building. CLI overrides: -Pkiteconfig.dryRun=true, -Pkiteconfig.backups=false.

Read-back

This extension implements KiteConfigValues, so every resolved value is readable from any build file in the project:

import io.github.yuroyami.kiteconfig.kiteConfig

versionCode = kiteConfig.versionCode.get()

That view is read-only and covers version, identity, locales, the shared module path, and the Android SDK levels. See KiteConfigValues for the full list and for the two values that resolve later than the rest.

Constructors

KiteConfigExtension

constructor()

Properties

android

val android: KiteConfigAndroidExtension

Android-only settings. Configure with kiteConfig { android { } }.

androidApplicationId

open override val androidApplicationId: Provider<String>

Android application id: the effective appId for Android.

appId

abstract override val appId: Property<String>

The reverse-DNS identifier shared by every platform.

appName

abstract override val appName: Property<String>

The display name users see on their home screen.

autoApply

abstract val autoApply: Property<Boolean>

Apply the configured source changes as part of an ordinary build.

backups

abstract val backups: Property<Boolean>

Keep a first-contact recovery copy before rewriting a file.

buildConfig

val buildConfig: KiteConfigBuildConfigExtension

Generated runtime constants for commonMain. Configure with kiteConfig { buildConfig { } }.

canonicalLocales

open override val canonicalLocales: Provider<List<String>>

Normalized, de-duplicated locale tags.

compileSdk

open override val compileSdk: Provider<Int>

Android API level the app compiles against.

desktop

val desktop: KiteConfigDesktopExtension

Compose Desktop settings. Configure with kiteConfig { desktop { } }.

desktopBuildNumber

open override val desktopBuildNumber: Provider<String>

The resolved desktop build number.

desktopBundleId

open override val desktopBundleId: Provider<String>

Desktop bundle id: the effective appId for desktop.

dryRun

abstract val dryRun: Property<Boolean>

Make the explicit source-changing tasks report what they would do and write nothing.

ignoreVersionGuards

abstract val ignoreVersionGuards: Property<Boolean>

Treat AGP, KGP, and Compose versions outside the tested range as supported.

ios

val ios: KiteConfigIosExtension

Apple-only settings. Configure with kiteConfig { ios { } }.

iosBuildNumber

open override val iosBuildNumber: Provider<String>

The resolved Apple build number, CFBundleVersion.

iosBundleId

open override val iosBundleId: Provider<String>

Apple bundle id: the effective appId for iOS.

iosMarketingVersion

open override val iosMarketingVersion: Provider<String>

The resolved Apple marketing version, CFBundleShortVersionString.

jvmTarget

open override val jvmTarget: Provider<Int>

The shared bytecode level, readable from any build file.

jvmToolchain

open override val jvmToolchain: Provider<Int>

The shared JDK selection, readable from any build file.

logo

val logo: KiteLogoScope

App icon art. Configure with kiteConfig { logo { } }.

minSdk

open override val minSdk: Provider<Int>

Lowest Android API level the app runs on.

modules

val modules: KiteConfigModulesExtension

Where your modules live. Configure with kiteConfig { modules { } }.

ndk

open override val ndk: Provider<String>

Pinned Android NDK version, in Android's major.minor.build form.

optIns

val optIns: KiteConfigNativeOptInsExtension

Kotlin/Native interop opt-in markers. Configure with kiteConfig { optIns { } }.

resolvedSharedProjectPath

open override val resolvedSharedProjectPath: Provider<String>

The selected shared KMP project path.

targetSdk

open override val targetSdk: Provider<Int>

Android API level the app targets.

version

abstract override val version: Property<String>

The release version you show to users, as x.y.z.

versionCode

open override val versionCode: Provider<Int>

The resolved Android versionCode for this build.

web

val web: KiteConfigWebExtension

Browser Kotlin/JS helpers. Configure with kiteConfig { web { } }.

Functions

android

fun android(action: Action<in KiteConfigAndroidExtension>)

Configure SDK levels, the Android id suffix, and the Play re-upload dial.

appIdFor

open override fun appIdFor(platform: KitePlatform): Provider<String>

The identifier platform receives, suffix or exact override applied.

appNameFor

open override fun appNameFor(platform: KitePlatform): Provider<String>

The app name as platform receives it, corner overrides applied.

buildConfig

fun buildConfig(action: Action<in KiteConfigBuildConfigExtension>)

Generate a Kotlin object of public runtime configuration.

desktop

fun desktop(action: Action<in KiteConfigDesktopExtension>)

Apply app identity, versions, and installer values to Compose Desktop.

ios

fun ios(action: Action<in KiteConfigIosExtension>)

Configure the Apple bundle suffix, build number, paths, and source sync.

jvm

fun jvm(action: Action<in KiteJvmScope>)

The JVM topic: the toolchain that builds and the bytecode level it emits.

locales

fun locales(action: Action<in KiteLocalesScope>)

The locales topic: the tag list every platform starts from.

logo

fun logo(action: Action<in KiteLogoScope>)

Point KiteConfig at your foreground and background art.

modules

fun modules(action: Action<in KiteConfigModulesExtension>)

Tell KiteConfig where the shared and Android application projects are.

only

fun only(vararg refs: KitePlatformRef)

This fact flows only to the given platforms.

optIns

fun optIns(action: Action<in KiteConfigNativeOptInsExtension>)

Add opt-in markers to the selected Kotlin/Native compilations.

skip

fun skip(vararg refs: KitePlatformRef)

This fact does not flow to the given platforms.

splash

fun splash(action: Action<in KiteSplashScope>)

The splash topic. Off until splash { enabled = true }.

version

fun version(action: Action<in KiteVersionScope>)

Details for version: the shared scheme and rebuild counter.

web

fun web(action: Action<in KiteConfigWebExtension>)

Configure optional browser Kotlin/JS source generation.

KiteConfigExtension

The law

The full surface

What you can inject where

Tasks

Read-back

See also

Constructors

Properties

Functions