readme.md
134 lines
| 5.1 KiB
| text/x-minidsrc
|
MarkdownLexer
/ common / readme.md
cin
|
r26 | # Gradle Common Sources Model | ||
| ## NAME | ||||
| `gradle-common/common` — набор плагинов для моделирования вариантов сборки, | ||||
|
cin
|
r27 | регистрации source sets и интеграции этой модели с toolchain-адаптерами. | ||
|
cin
|
r26 | |||
| ## SYNOPSIS | ||||
| ```groovy | ||||
| plugins { | ||||
| id 'org.implab.gradle-variants-sources' | ||||
| } | ||||
| variants { | ||||
| layer('mainBase') | ||||
| layer('mainAmd') | ||||
| variant('browser') { | ||||
| role('main') { layers('mainBase', 'mainAmd') } | ||||
| } | ||||
| } | ||||
| variantSources { | ||||
| bind('mainBase') { | ||||
| configureSourceSet { | ||||
| declareOutputs('compiled') | ||||
| } | ||||
| } | ||||
| bind('mainAmd').sourceSetNamePattern = '{variant}{layerCap}' | ||||
| whenRegistered { sourceSetName() } | ||||
| whenBound { ctx -> | ||||
| ctx.configureSourceSet { | ||||
| declareOutputs('typings') | ||||
| } | ||||
| } | ||||
| } | ||||
| ``` | ||||
| ## DESCRIPTION | ||||
| Модуль состоит из трех логических частей: | ||||
| - `variants` — декларативная доменная модель сборки; | ||||
|
cin
|
r27 | - `sources` — модель физически регистрируемых source sets; | ||
|
cin
|
r26 | - `variantSources` — адаптер, который связывает первые две модели. | ||
| Ниже раскрытие каждой части. | ||||
| ### variants | ||||
| `variants` задает структуру пространства сборки: какие есть слои, какие роли | ||||
|
cin
|
r30 | используют эти слои в каждом варианте, какие есть атрибуты и artifact slots. | ||
| Модель не создает задачи и не привязана к TS/JS. | ||||
|
cin
|
r26 | |||
| Практический смысл: | ||||
| - формализовать архитектуру сборки; | ||||
| - дать адаптерам единый источник правды. | ||||
| ### sources | ||||
| `sources` описывает независимые source sets (`GenericSourceSet`) с именованными | ||||
| outputs. Это уже "физический" уровень, к которому удобно привязывать задачи, | ||||
| артефакты и task inputs/outputs. | ||||
| Практический смысл: | ||||
| - создать единый контракт по входам/выходам; | ||||
| - регистрировать результаты задач как outputs source set; | ||||
| - минимизировать ручные `dependsOn` за счет модели outputs. | ||||
| ### variantSources | ||||
|
cin
|
r27 | `variantSources` регистрирует source sets на основе `variants`, применяет | ||
|
cin
|
r26 | конфигурацию layer-bindings и отдает события (`whenRegistered`, `whenBound`) для | ||
| адаптеров других плагинов. | ||||
| Практический смысл: | ||||
| - переводить логическую модель `variants` в executable-модель `sources`; | ||||
|
cin
|
r27 | - навешивать политики toolchain на зарегистрированные source sets; | ||
|
cin
|
r26 | - синхронизировать плагины через replayable callback-контракт. | ||
| ## DOMAIN MODEL | ||||
|
cin
|
r38 | - `BuildLayer` — canonical identity-model объявленного слоя. | ||
|
cin
|
r30 | - `BuildVariant` — агрегат ролей, атрибутов, артефактных слотов. | ||
|
cin
|
r38 | - `BuildRole` — роль внутри варианта, содержит ссылки на declared layer names. | ||
|
cin
|
r27 | - `GenericSourceSet` — зарегистрированный набор исходников и outputs. | ||
|
cin
|
r38 | - `LayerBindingSpec` — публичный DSL-contract adapter policy/callbacks для слоя. | ||
|
cin
|
r31 | - `SourceSetRegistration` — payload события регистрации source set. | ||
| - `SourceSetUsageBinding` — payload события usage-binding. | ||||
|
cin
|
r26 | |||
| ## EVENT CONTRACT | ||||
| - `whenRegistered`: | ||||
| - событие нового уникального source set name; | ||||
| - replayable. | ||||
| - `whenBound`: | ||||
| - событие каждой usage-связки `variant/role/layer`; | ||||
| - replayable. | ||||
| Closure callbacks работают в delegate-first режиме (`@DelegatesTo`). Для | ||||
| вложенных closure рекомендуется явный параметр (`ctx -> ...`). | ||||
| ## KEY CLASSES | ||||
| - `SourcesPlugin` — регистрирует extension `sources`. | ||||
| - `GenericSourceSet` — модель источников/outputs для конкретного имени. | ||||
| - `VariantsPlugin` — регистрирует extension `variants` и lifecycle finalize. | ||||
| - `BuildVariantsExtension` — корневой API модели вариантов. | ||||
|
cin
|
r30 | - `BuildVariant` — API ролей, attributes и artifact slots варианта. | ||
|
cin
|
r26 | - `VariantsSourcesPlugin` — применяет `variants` + `sources` и запускает адаптер. | ||
|
cin
|
r27 | - `VariantSourcesExtension` — API bind/events registration. | ||
|
cin
|
r38 | - `LayerBindingSpec` — слой-конкретный DSL для policy/configuration source set. | ||
|
cin
|
r31 | - `SourceSetRegistration` — payload `whenRegistered(...)`. | ||
| - `SourceSetUsageBinding` — payload `whenBound(...)`. | ||||
|
cin
|
r26 | |||
| ## NOTES | ||||
| - Marker ids: | ||||
| - `org.implab.gradle-variants` | ||||
| - `org.implab.gradle-variants-sources` | ||||
| - `SourcesPlugin` пока class-only (без marker id). | ||||
| ## SEE ALSO | ||||
| - `sources-plugin.md` | ||||
| - `variants-plugin.md` | ||||
| - `variant-sources-plugin.md` | ||||