DOCSEARCHbyAlgolia
Submit Docs

BuildKonfig Documentation

repository·master·Indexed 22 days ago

https://github.com/yshrsmz/buildkonfig

A Gradle plugin that generates a BuildConfig class for Kotlin Multiplatform and Kotlin/JVM projects. It enables developers to embed Gradle-defined values into Kotlin source code, supporting target-dependent values via an expect/actual pattern and simulated product flavors. Requires Kotlin 2.1.0 or later and Gradle 8 or later.

Tokens
2K
Snippets
5
Records
9
Agent score
29%

What's inside BuildKonfig

  1. Overview of BuildKonfig

    master
    BuildKonfig is a Gradle plugin designed to provide BuildConfig functionality for Kotlin Multiplatform (KMP) and Kotlin/JVM projects. It allows you to embed values defined in your Gradle files directly into your Kotlin code, providing a unified way to handle configuration across different platforms (like Android and iOS) without needing platform-specific setup for each.

  2. Limitations with HMPP (Intermediate SourceSets)

    master

    BuildKonfig supports Hierarchical Multiplatform Projects (HMPP), but there is a restriction:

    You cannot define targetConfigs for both an intermediate source set and its children.

    Because BuildKonfig uses expect/actual to provide values, if you provide a configuration for an intermediate source set (e.g., appMain), the actual declaration of the BuildKonfig object is created in that source set. Any attempt to add actual declarations in child source sets (e.g., androidMain or desktopMain) will result in a compile-time error.

  3. Configure BuildKonfig for non-multiplatform projects

    master

    BuildKonfig works with standalone Kotlin/JVM projects. Apply the org.jetbrains.kotlin.jvm plugin instead of multiplatform. A single concrete object is generated into the main source set without an expect/actual split.

    For Kotlin/JS, use the Kotlin Multiplatform plugin with a js() target, as the standalone org.jetbrains.kotlin.js plugin was removed in Kotlin 2.4.0.

    Note: targetConfigs are ignored in single-target projects and will log a warning if declared.

    import com.codingfeline.buildkonfig.compiler.FieldSpec.Type.STRING

plugins {
    kotlin("jvm")
    id("com.codingfeline.buildkonfig")
}

buildkonfig {
    packageName = "com.example.app"

    defaultConfigs {
        buildConfigField(STRING, "name", "value")
    }
}

  4. Install and configure BuildKonfig

    master

    BuildKonfig allows you to generate a Kotlin object containing configuration values.

    Requirements

    • Kotlin 2.1.0 or later
    • A Kotlin Multiplatform or Kotlin/JVM project (for Kotlin/JS, use the KMP js() target)
    • Gradle 8 or later

    Basic Setup (Kotlin DSL)

    Apply the plugin and configure the buildkonfig block. You must provide a packageName and a defaultConfigs block.

    import com.codingfeline.buildkonfig.compiler.FieldSpec.Type.STRING

plugins {
    kotlin("multiplatform")
    id("com.codingfeline.buildkonfig")
}

buildkonfig {
    packageName = "com.example.app"
    defaultConfigs {
        buildConfigField(STRING, "name", "value")
    }
}

    To generate the files, run the generateBuildKonfig task, which is also automatically triggered during Kotlin compilation tasks.

  5. Configure target-dependent values

    master

    You can use targetConfigs to provide different values for specific Kotlin targets. When targetConfigs are used, BuildKonfig is generated using an expect/actual pattern.

    Note on Kotlin 2.x (K2): Because the K2 compiler does not allow expect const val, the common-side declaration is emitted as a plain val even if const = true is set. The target-specific actual declaration will still be a const val, meaning it is a compile-time constant within that target, but cannot be used as a compile-time constant in common code (e.g., in when branches or annotation arguments).

    Example (Kotlin DSL)

    buildkonfig {
    packageName = "com.example.app"

    defaultConfigs {
        buildConfigField(STRING, "name", "default_value")
    }

    targetConfigs {
        create("android") {
            buildConfigField(STRING, "name", "android_value")
        }
        create("ios") {
            buildConfigField(STRING, "name", "ios_value")
        }
    }
}

  6. Simulate product flavors using BuildKonfig

    master

    Since Kotlin Multiplatform does not natively support Android-style product flavors, you can mimic this behavior by defining a flavor property in gradle.properties and using it to select configurations.

    1. Set a default flavor in gradle.properties: buildkonfig.flavor=dev

    2. Use the flavor as an argument in defaultConfigs and targetConfigs within your build.gradle(.kts) file.

    To override the flavor via CLI (e.g., in CI): ./gradlew build -Pbuildkonfig.flavor=release

    Precedence Rules

    When multiple configurations define the same field, the following hierarchy determines the winner (strongest to weakest): Flavored TargetConfig > TargetConfig > Flavored DefaultConfig > DefaultConfig

    // Example of flavored configuration in Kotlin DSL
buildkonfig {
    packageName = "com.example.app"

    defaultConfigs {
        buildConfigField(STRING, "name", "base_value")
    }

    // Flavor-specific default config
    defaultConfigs("dev") {
        buildConfigField(STRING, "name", "dev_value")
    }

    targetConfigs("dev") {
        create("ios") {
            buildConfigField(STRING, "name", "dev_ios_value")
        }
    }
}

  7. Try out the BuildKonfig samples

    master

    The repository contains two sample projects to demonstrate usage:

    • sample: Uses the traditional Groovy DSL.
    • sample-kts: Uses the Kotlin DSL.

    To run the samples, you can use the following commands. Note that BuildKonfig will be generated in the ./sample/build/buildkonfig directory.

    # Publish the latest version of the plugin to test maven repository (./build/localMaven)
$ ./gradlew publishAllPublicationsToTestMavenRepository -PRELEASE_SIGNING_ENABLED=false

# Try out the samples.
# BuildKonfig will be generated in ./sample/build/buildkonfig
$ ./gradlew -p sample generateBuildKonfig

  8. BuildKonfig configuration reference

    master

    The following keys and methods are available within the buildkonfig { ... } block:

    • packageName: (Required) The package name where the generated BuildKonfig object will be placed.
    • objectName: The name of the generated object. Defaults to BuildKonfig.
    • exposeObjectWithName: Sets the name of the generated object and makes it public.
    • defaultConfigs: Sets values common to all targets. If omitted, a warning is logged and code generation is skipped.
    • targetConfigs: Sets target-specific values. Can overwrite values from defaultConfigs.
    • buildConfigField(type: String, name: String, value: String): Adds a new value or overwrites an existing one.
    • buildConfigField(type: String, name: String, value: String, nullable: Boolean = false, const: Boolean = false): Adds a field with optional nullable and const modifiers.