implab/gradle-common Commit - r44:ae7ec3f08ac3

more documentation

cin -

r44:ae7ec3f08ac3 default

parent child

Context file:

r44:ae7ec3f08ac3

Collapse all files

variant_sources_precedence.md +68 0

@@ -164,6 +164,8 Policy rules:
164	- once chosen, the policy cannot be changed later	164	- once chosen, the policy cannot be changed later
165	- the policy is single-valued; it is not intended to be switched during further	165	- the policy is single-valued; it is not intended to be switched during further
166	configuration	166	configuration
		167	- the enforcement point is the first selector registration itself; finalization
		168	of `variants` alone does not freeze this policy
167		169
168	Operationally:	170	Operationally:
169		171
@@ -176,6 +178,70 Operationally:
176		178
177	---	179	---
178		180
		181	## Compile-Unit Naming Policy
		182
		183	`variantSources` also exposes a policy for projecting compile units to symbolic
		184	source-set names:
		185
		186	```groovy
		187	variantSources {
		188	namingPolicy {
		189	failOnNameCollision()
		190	}
		191	}
		192	```
		193
		194	Base projected name:
		195
		196	- `sourceSetName = variantName + capitalize(layerName)`
		197
		198	Example:
		199
		200	- `(browser, main)` -> `browserMain`
		201	- `(browser, rjs)` -> `browserRjs`
		202
		203	Available modes:
		204
		205	- `failOnNameCollision()` rejects finalized compile-unit models that project the
		206	same base name for different compile units
		207	- `resolveNameCollision()` resolves such collisions deterministically
		208
		209	### `resolveNameCollision()` semantics
		210
		211	Conflicting compile units are ordered canonically by:
		212
		213	```text
		214	(variant.name, layer.name)
		215	```
		216
		217	Name assignment in a conflicting group is:
		218
		219	- the first compile unit keeps the base name
		220	- the second gets suffix `2`
		221	- the third gets suffix `3`
		222	- and so on
		223
		224	Example:
		225
		226	- `(foo, variantBar)` and `(fooVariant, bar)` both project to `fooVariantBar`
		227	- after canonical ordering:
		228	- `(foo, variantBar)` -> `fooVariantBar`
		229	- `(fooVariant, bar)` -> `fooVariantBar2`
		230
		231	### Fixation Point
		232
		233	Naming policy is fixed when the finalized `VariantSourcesContext` is created.
		234
		235	Operationally this means:
		236
		237	- policy selection must happen before `variantSources.whenFinalized(...)`
		238	becomes observable
		239	- compile-unit names are projected and validated before queued
		240	`whenFinalized(...)` callbacks are replayed
		241	- changing naming policy from inside a `whenFinalized(...)` callback is too late
		242
		243	---
		244
179	## Example	245	## Example
180		246
181	```groovy	247	```groovy
@@ -265,5 +331,7 variant < layer < unit
265	- already materialized targets are handled by `lateConfigurationPolicy(...)`	331	- already materialized targets are handled by `lateConfigurationPolicy(...)`
266	- the late-configuration policy must be selected before the first selector rule	332	- the late-configuration policy must be selected before the first selector rule
267	and cannot be changed later	333	and cannot be changed later
		334	- compile-unit naming is governed by `namingPolicy(...)`
		335	- by default, name collisions fail fast during finalized context creation
268	- `variants` defines what exists	336	- `variants` defines what exists
269	- `variantSources` defines how those compile units are materialized as source sets	337	- `variantSources` defines how those compile units are materialized as source sets

variants/src/main/java/org/implab/gradle/variants/sources/SourceSetMaterializer.java +7 -3

             import org.implab.gradle.common.sources.GenericSourceSet;
             /**
-             * Materializes symbolic source set names into actual GenericSourceSet
+             * Materializes symbolic source set names into actual {@link GenericSourceSet}
              * instances.
+             *
+             * <p>Symbolic names are assigned from the finalized compile-unit model using
+             * the selected
+             * {@link VariantSourcesExtension#namingPolicy(org.gradle.api.Action)}.
              */
             public interface SourceSetMaterializer {
                 /**
                  * Returns a lazy provider for the source set corresponding to the compile unit.
                  *
-                 * The provider is stable and cached per compile unit.
+                 * <p>The provider is stable and cached per compile unit.
                  */
                 NamedDomainObjectProvider<GenericSourceSet> getSourceSet(CompileUnit unit);
-            }
  No newline at end of file

variants/src/main/java/org/implab/gradle/variants/sources/VariantSourcesContext.java +3 -1

             /**
              * Registry of symbolic source set names produced by sources projection.
              *
-             * Identity in this registry is the GenericSourceSet name.
+             * <p>Identity in this registry is the {@link GenericSourceSet} name assigned
+             * by the finalized
+             * {@link VariantSourcesExtension#namingPolicy(org.gradle.api.Action)}.
              */
             public interface VariantSourcesContext {

variants/src/main/java/org/implab/gradle/variants/sources/VariantSourcesExtension.java +59 0

                  * <li>once selected, it cannot be changed later;</li>
                  * <li>the policy controls both diagnostics and late-application semantics.</li>
                  * </ul>
+                 *
+                 * <p>If not selected explicitly, the default is
+                 * {@link LateConfigurationPolicySpec#failOnLateConfiguration()}.
                  */
                 void lateConfigurationPolicy(Action<? super LateConfigurationPolicySpec> action);
                     lateConfigurationPolicy(Closures.action(closure));
                 }
+                /**
+                 * Selects how compile-unit name collisions are handled when the finalized
+                 * source context is created.
+                 *
+                 * <p>This policy is single-valued:
+                 * <ul>
+                 * <li>it must be selected before the finalized
+                 * {@link VariantSourcesContext} becomes observable through
+                 * {@link #whenFinalized(Action)};</li>
+                 * <li>once the context is being created, the policy is fixed and cannot be
+                 * changed later;</li>
+                 * <li>the policy governs validation of compile-unit names produced by the
+                 * source-set materializer.</li>
+                 * </ul>
+                 *
+                 * <p>If not selected explicitly, the default is
+                 * {@link NamingPolicySpec#failOnNameCollision()}.
+                 */
                 void namingPolicy(Action<? super NamingPolicySpec> action);
                 default void namingPolicy(Closure<?> closure) {
                     namingPolicy(Closures.action(closure));
                 }
+                /**
+                 * Registers a selector rule for all compile units of the given layer.
+                 *
+                 * <p>Registering the first selector rule fixes the selected
+                 * {@link #lateConfigurationPolicy(Action)} for the remaining extension
+                 * lifecycle.
+                 */
                 void layer(String layerName, Action<? super GenericSourceSet> action);
                 default void layer(String layerName, Closure<?> closure) {
                     layer(layerName, Closures.action(closure));
                 }
+                /**
+                 * Registers a selector rule for all compile units of the given variant.
+                 *
+                 * <p>Registering the first selector rule fixes the selected
+                 * {@link #lateConfigurationPolicy(Action)} for the remaining extension
+                 * lifecycle.
+                 */
                 void variant(String variantName, Action<? super GenericSourceSet> action);
                 default void variant(String variantName, Closure<?> closure) {
                     variant(variantName, Closures.action(closure));
                 }
+                /**
+                 * Registers a selector rule for one exact compile unit.
+                 *
+                 * <p>Registering the first selector rule fixes the selected
+                 * {@link #lateConfigurationPolicy(Action)} for the remaining extension
+                 * lifecycle.
+                 */
                 void unit(String variantName, String layerName, Action<? super GenericSourceSet> action);
                 /**
                  * <li>if called before variants finalization, action is queued
                  * <li>if called after variants finalization, action is invoked immediately
                  * </ul>
+                 *
+                 * <p>By the time this callback becomes observable, compile-unit naming
+                 * policy has already been fixed and symbolic source-set names for finalized
+                 * compile units are determined.
                  */
                 void whenFinalized(Action<? super VariantSourcesContext> action);
                 }
                 interface NamingPolicySpec {
+                    /**
+                     * Rejects finalized compile-unit models that project the same source-set
+                     * name for different compile units.
+                     */
                     void failOnNameCollision();
+                    /**
+                     * Resolves name collisions deterministically for the finalized
+                     * compile-unit model.
+                     *
+                     * <p>Conflicting compile units are ordered canonically by
+                     * {@code (variant.name, layer.name)}. The first unit keeps the base
+                     * projected name, and each next unit receives a numeric suffix
+                     * ({@code 2}, {@code 3}, ...).
+                     */
                     void resolveNameCollision();
                 }
             }

variants_variant_sources.md +104 -8

             * the DSL is internal to source materialization
             * the source of truth for unit existence is already finalized in `VariantsView`
-            * `GenericSourceSetMaterializer` returns `NamedDomainObjectProvider<GenericSourceSet>`
+            * `SourceSetMaterializer` returns `NamedDomainObjectProvider<GenericSourceSet>`
             * adapters may need to refine source-related behavior after `variants` is finalized
             Therefore:
             * a closed domain model
             * an open infrastructure/materialization model
+            This openness is still constrained by explicit policy fixation points:
+            * late-configuration policy is fixed when the first selector rule is registered
+            * naming policy is fixed when the finalized `VariantSourcesContext` is created
             ---
             ## Late configuration policy
             * selector rules here mean `variant(...)`, `layer(...)`, and `unit(...)`
             * once chosen, it cannot be changed later
             * it controls runtime behavior, not just a stored value
+            * the enforcement point is the first selector registration itself, not variants
+              finalization in isolation
             For source sets configured before materialization, selector precedence remains:
             ---
+            ## Compile-unit naming policy
+            Source-set naming is treated as a separate policy concern from selector
+            registration.
+            Conceptually, `variantSources` exposes:
+            ```groovy
+            variantSources {
+                namingPolicy {
+                    failOnNameCollision()
+                }
+            }
+            ```
+            The base projected name of a compile unit is:
+            ```text
+            variantName + capitalize(layerName)
+            ```
+            Examples:
+            * `(browser, main)` -> `browserMain`
+            * `(browser, rjs)` -> `browserRjs`
+            Available modes are:
+            * `failOnNameCollision()` - reject finalized compile-unit models that project
+              the same source-set name for different compile units
+            * `resolveNameCollision()` - resolve such conflicts deterministically
+            ### `resolveNameCollision()` semantics
+            Conflicting compile units are ordered canonically by:
+            ```text
+            (variant.name, layer.name)
+            ```
+            Within one conflicting group:
+            * the first compile unit keeps the base name
+            * the second gets suffix `2`
+            * the third gets suffix `3`
+            * and so on
+            For example, if:
+            * `(foo, variantBar)` projects to `fooVariantBar`
+            * `(fooVariant, bar)` also projects to `fooVariantBar`
+            then canonical ordering yields:
+            * `(foo, variantBar)` -> `fooVariantBar`
+            * `(fooVariant, bar)` -> `fooVariantBar2`
+            ### Fixation point
+            Naming policy is fixed when the finalized `VariantSourcesContext` is created.
+            Operationally this means:
+            * naming policy must be selected before `variantSources.whenFinalized(...)`
+              becomes observable
+            * compile-unit names are projected and validated before queued
+              `whenFinalized(...)` callbacks are replayed
+            * changing naming policy from inside a `whenFinalized(...)` callback is too late
+            This differs intentionally from late-configuration policy:
+            * late-configuration policy is fixed by the first selector rule
+            * naming policy is fixed by finalized-context creation
+            ---
             ## `VariantSourcesContext`
             `variantSources.whenFinalized(...)` remains useful, but not because `variantSources` itself is frozen.
             * `CompileUnitsView`
             * `RoleProjectionsView`
-            * `GenericSourceSetMaterializer`
+            * `SourceSetMaterializer`
+            By the time the context becomes observable:
+            * compile-unit naming policy is already fixed
+            * symbolic source-set names for finalized compile units are already determined
             Conceptually:
             interface VariantSourcesContext {
                 CompileUnitsView getCompileUnits();
                 RoleProjectionsView getRoleProjections();
-                GenericSourceSetMaterializer getSourceSets();
+                SourceSetMaterializer getSourceSets();
             }
             ```
             ---
-            ## `GenericSourceSetMaterializer`
+            ## `SourceSetMaterializer`
             ### Purpose
-            `GenericSourceSetMaterializer` is the official source of truth for materialized source sets.
+            `SourceSetMaterializer` is the official source of truth for materialized source sets.
             It is responsible for:
             * lazy creation of `GenericSourceSet`
+            * projecting finalized compile units to symbolic source-set names
+            * validating or resolving name collisions according to naming policy
             * applying `layerRule`
             * connecting a compile unit to a source set provider
             * exposing source sets to adapters
             ### Conceptual API
             ```java
-            interface GenericSourceSetMaterializer {
+            interface SourceSetMaterializer {
                 NamedDomainObjectProvider<GenericSourceSet> getSourceSet(CompileUnit unit);
             }
             ```
             ---
-            ## Why `GenericSourceSetMaterializer` should own `layerRule` application
+            ## Why `SourceSetMaterializer` should own `layerRule` application
             If adapters applied `layerRule` directly, responsibility would leak across multiple layers:
             Instead:
             * `layerRule` is DSL/spec-level
-            * `GenericSourceSetMaterializer` is execution/materialization-level
+            * `SourceSetMaterializer` is execution/materialization-level
             * adapters are consumption-level
             This gives a much cleaner separation.
             Materialized `GenericSourceSet` objects should remain behind a lazy API.
+            ### 7. Make name-collision behavior explicit
+            Compile-unit naming must be governed by an explicit policy, not by incidental
+            materialization order.
             ---
             ## Summary
             * layer source rules
             * compile-unit source set materialization
+            * compile-unit naming policy
             * adapter-facing `GenericSourceSet` providers
             ### Derived views

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No TODOs yet

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages