readme.md
135 lines
| 5.3 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') } | ||||
| link('mainBase', 'mainAmd', 'ts:api') | ||||
| } | ||||
| } | ||||
| 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` задает структуру пространства сборки: какие есть слои, какие роли | ||||
| используют эти слои в каждом варианте, какие направленные связи между слоями | ||||
| существуют. Модель не создает задачи и не привязана к TS/JS. | ||||
| Практический смысл: | ||||
| - формализовать архитектуру сборки; | ||||
| - централизовать валидацию связей; | ||||
| - дать адаптерам единый источник правды. | ||||
| ### 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 | ||||
| - `BuildLayer` — глобальный идентификатор слоя. | ||||
| - `BuildVariant` — агрегат ролей, связей, атрибутов, артефактных слотов. | ||||
| - `BuildRole` — роль внутри варианта, содержит ссылки на layer names. | ||||
|
cin
|
r27 | - `LayerLink` — ориентированная связь `from -> to` в графе определенного `kind`. | ||
| - `GenericSourceSet` — зарегистрированный набор исходников и outputs. | ||||
| - `BuildLayerBinding` — правила registration source set для конкретного layer. | ||||
| - `SourceSetContext` — контекст callback-событий registration. | ||||
|
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 модели вариантов. | ||||
| - `BuildVariant` — API ролей, links, attributes и artifact slots варианта. | ||||
| - `VariantsSourcesPlugin` — применяет `variants` + `sources` и запускает адаптер. | ||||
|
cin
|
r27 | - `VariantSourcesExtension` — API bind/events registration. | ||
|
cin
|
r26 | - `BuildLayerBinding` — слой-конкретный DSL для имени и конфигурации source set. | ||
| - `SourceSetContext` — payload событий и sugar `configureSourceSet(...)`. | ||||
| ## 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` | ||||