variantSources: selectors and precedence

variantSources configures source-set materialization over the compile-unit space.

A compile unit is defined as:

• (variant, layer)

This means:

• variant defines compilation semantics
• layer defines compilation partitioning

The variantSources DSL does not introduce a separate source model. Instead, it provides configuration selectors over the existing compile-unit space.

Selectors

Three selectors are available:

• variant(...)
• layer(...)
• unit(...)

They all target the same set of compile units, but at different levels of specificity.

variant(...)

variant(...) applies configuration to all compile units that belong to the given variant.

Example:

variantSources {
    variant("browser") {
        declareOutputs("js", "dts")
    }
}

This affects all compile units of browser, for example:

• (browser, main)
• (browser, rjs)
• (browser, test)

Use this selector for variant-wide conventions.

layer(...)

layer(...) applies configuration to all compile units that use the given layer.

Example:

variantSources {
    layer("main") {
        set("ts") {
            srcDir("src/main/ts")
        }
    }
}

This affects all compile units with layer main, for example:

• (browser, main)
• (nodejs, main)
• (electron, main)

Use this selector for cross-variant layer conventions.

unit(...)

unit(...) applies configuration to one exact compile unit.

Example:

variantSources {
    unit("browser", "main") {
        set("resources") {
            srcDir("src/browserMain/resources")
        }
    }
}

This affects only:

• (browser, main)

Use this selector for the most specific adjustments.

Precedence

For each compile unit, source-set configuration is applied in the following order:

variant < layer < unit

This means:

1. variant(...) actions are applied first
2. layer(...) actions are applied next
3. unit(...) actions are applied last

Each next level is allowed to refine or override the previous one.

Within the same level

Within the same selector level, actions are applied in registration order.

For example, if two plugins both configure layer("main"), their actions are applied in the same order in which they were registered.

Example

variantSources {
    variant("browser") {
        declareOutputs("js", "dts")
    }

    layer("main") {
        set("ts") {
            srcDir("src/main/ts")
        }
    }

    unit("browser", "main") {
        set("resources") {
            srcDir("src/browserMain/resources")
        }
    }
}

For compile unit (browser, main) the effective configuration is built in this order:

1. variant("browser")
2. layer("main")
3. unit("browser", "main")

For compile unit (browser, rjs) the effective configuration is built in this order:

1. variant("browser")
2. layer("rjs") if present
3. unit("browser", "rjs") if present

For compile unit (nodejs, main) the effective configuration is built in this order:

1. variant("nodejs") if present
2. layer("main")
3. unit("nodejs", "main") if present

Model boundary

These selectors do not define compile units. Compile units are derived from finalized variants.

variantSources only configures how source sets are materialized for those units.

This means:

• variants is the source of truth for compile-unit existence
• variantSources is the source of truth for compile-unit source-set configuration

Operational semantics

The variantSources API is exposed through a finalized context.

Conceptually, configuration is registered against finalized model objects, while DSL sugar may still use names for convenience.

Internally, selector-based configuration is accumulated and later applied by the source-set materializer when a GenericSourceSet is created for a compile unit.

This guarantees that:

• selector precedence is stable
• registration order is preserved
• configuration does not depend on the materialization moment
• adapters do not need to depend on raw Gradle lifecycle timing

Summary

• compile unit space is (variant, layer)
• variant(...), layer(...), and unit(...) are selectors over that space
• precedence is:

variant < layer < unit

• registration order is preserved within the same selector level
• variants defines what exists
• variantSources defines how those compile units are materialized as source sets