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"
    version = "1.4.0"
    id      = "com.example.jetzy"
}

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") {
        ios("Jetzy Lite")          // platform value override
        skip(desktop)              // this fact does not flow there
    }

    jvmTarget = 21                 // Java + Kotlin JVM level, whole build

    id("com.example.jetzy") {
        android { suffix = ".android" }   // applicationId = base + suffix
        ios     { suffix = ".ios" }       // bundle id     = base + suffix
        desktop { suffix = ".desktop" }
    }

    version("1.4.0") {
        // formula { v -> ... }        // optional: your own build-number formula
        android {
            reupload = 1               // re-upload same version to Play
            shipped  = 1001003090      // highest code ever shipped, guard
        }
        ios { shipped = "1001003090" }
        desktop { shipped = "1001003090" }
    }

    locales {
        pin("en", "ar", "fr")          // hand list, detection skipped
        filterAndroidRes = true        // drop Android res outside the list
    }

    logo {
        foreground = file("art/logo-fg.png")
        backgroundColor = "#0B0B0F"
        android { safeZone = 0.611 }
        desktop { roundMac = true }    // desktop icons flow from presence
        rewrite { replaceOld = true }  // arms kiteRewriteLogo (source edits)
    }

    splash {
        // empty block already works: art defaults to logo, plate to its color
        dark { backgroundColor = "#000000" }
        android { theme = "AppTheme" }     // your app theme; the generated
                                           //   KiteSplash style inherits it
        rewrite { }                        // arms the iOS launch-screen delivery
    }

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

    android { sdk(min = 26, target = 36, compile = 36) }

    ios {
        deploymentTarget = "15.0"
        rewrite {                      // arms kiteRewriteXcode (source edits)
            targets("iosApp")
            cleanPlist = true
        }
    }

    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

    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, `appName`, `id`, `version`, `locales`, `logo`, `splash`	flow control, at root = platform master
`android("v")` / `ios("v")` / `desktop("v")`	`appName`	platform value override
`android { }` / `ios { }` / `desktop { }` corner	`id`, `version`, `logo`	platform detail scope
`pin`	`version` corners, `locales`	manual value, machinery skipped
`reupload`, `shipped`, `formula`	`version` and its corners	store counter, guard floor, number formula
`suffix`	`id` corners	appended to the base id
`rewrite { }`	`logo`, `splash`, `ios`	the only acting word, arms a task
`dark { }`	`splash`	dark-mode variant
typed `*Field(...)`	`buildConfig`	generated constants

Tasks

kiteCheck, kiteDoctor, kiteVerify, kitePlan are read-only and always safe. kiteRewriteLogo and kiteRewriteXcode run only when armed by a rewrite { } block and only when you invoke them. 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: id plus its android corner suffix.

appName

abstract override val appName: Property<String>

The display name users see on their home screen.

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: id plus its desktop corner suffix.

dryRun

abstract val dryRun: Property<Boolean>

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

abstract override val id: Property<String>

Reverse-DNS id base shared by every platform. Simple form of id.

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: id plus its ios corner suffix.

iosMarketingVersion

open override val iosMarketingVersion: Provider<String>

The resolved Apple marketing version, CFBundleShortVersionString.

jvmTarget

abstract override val jvmTarget: Property<Int>

Java and Kotlin JVM level for the whole build, for example 21.

logo

val logo: KiteConfigLogoExtension

App icon installation. 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.

appName

fun appName(value: String, action: Action<in KiteAppNameScope>)

Detailed form of appName: per-platform overrides and flow modifiers.

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.

fun id(value: String, action: Action<in KiteIdScope>)

Detailed form of id: per-platform suffix corners and flow modifiers.

ios

fun ios(action: Action<in KiteConfigIosExtension>)

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

locales

fun locales(action: Action<in KiteLocalesScope>)

The locales topic: pinned list, Android res filter, and flow modifiers.

logo

fun logo(action: Action<in KiteConfigLogoExtension>)

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): <Error class: unknown class>

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): <Error class: unknown class>

This fact does not flow to the given platforms.

splash

fun splash(action: Action<in KiteSplashScope>)

The splash topic: launch-screen art. Presence flows Android and desktop.

version

fun version(value: String, action: Action<in KiteVersionScope>)

Detailed form of version: the shared formula and platform corners.

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