1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
---
title: Плагины
description: API плагинов Tazel и плагин Gradle, который собирает плагин.
---
<!-- SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> -->
<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
Плагин Tazel — это JAR на Kotlin или Java, который добавляет блоки в файлы проекта и шаги в сборку: например, блок
`cmake { }`, который настраивает и собирает проект CMake до компиляции целей модуля.
::note
Эта версия Tazel не загружает плагины: в `MODULE.kts` нет блока `plugins`. API и плагин Gradle ниже — версия 1 того,
с чем компилируются плагины.
::
## API
Библиотека `com.progmasoft.tazel:tazel-api` содержит пакет `com.progmasoft.api.tazel.dsl.plugin`.
| Тип | Что это |
| --- | --- |
| `ProjectPlugin` | класс плагина: Tazel вызывает `apply(context)` один раз для каждого модуля, который его объявляет |
| `ProjectPluginContext` | регистрирует расширения плагина, записывает значения в план модуля и выполняет код после файлов проекта |
| `PluginExtensions.require(name)` | `ExtensionScope` расширения, из функции DSL плагина |
| `ExtensionScope.buildStep(name, step)` | добавляет шаг в сборку; шаги идут в порядке добавления, до компиляции целей |
| `BuildStep`, `BuildContext` | шаг и то, с чем он выполняется: корень проекта, каталог результатов, режим сборки, хост, `run`, `capture`, `findProgram`, `status`, `warn` и `fail` |
| `Host` | операционная система и архитектура машины, на которой работает Tazel |
```kotlin
class CMakePlugin : ProjectPlugin {
override fun apply(context: ProjectPluginContext) {
context.registerExtension("cmake")
}
}
fun cmake(block: CMakeScope.() -> Unit) {
val settings = CMakeScope().apply(block)
PluginExtensions.require("cmake").buildStep("configure") { context ->
val status = context.run(listOf("cmake", "-S", settings.source, "-B", context.workDirectory.toString()))
if (status != 0) context.fail("cmake exited with $status")
}
}
```
Плагин работает с теми же правами, что и Tazel: его код не изолирован. Два плагина одного модуля не могут занять одно
и то же имя расширения.
## Плагин Gradle
Плагин Gradle `com.progmasoft.tazel.plugin` собирает JAR плагина. Он добавляет репозиторий API,
`https://maven.progmasoft.com/tazel`, зависимость `tazelApi()` и блок `tazelPlugin { }` и записывает в JAR дескриптор
плагина, `META-INF/tazel-plugin.properties`, и его запись сервиса.
```kotlin
plugins {
kotlin("jvm") version "2.4.0"
id("com.progmasoft.tazel.plugin") version "0.1.0"
}
dependencies {
tazelApi()
}
tazelPlugin {
group = "com.example"
name = "cmake"
version = "0.1.0"
pluginClass = "com.example.cmake.CMakePlugin"
imports.add("com.example.cmake.*")
description = "Builds CMake projects before the targets of a module."
license = "MIT"
}
```
| Настройка | Значение |
| --- | --- |
| `group` | обратный домен вроде `com.example`; обязательно |
| `name` | имя плагина в его группе; обязательно |
| `version` | семантическая версия; обязательно |
| `pluginClass` | класс, реализующий `ProjectPlugin`; обязательно |
| `imports` | пакеты, которые файлы проекта импортируют без явной записи |
| `description`, `authors`, `license`, `homepage`, `repository` | что показывается о плагине |
`tazelApi()` добавляет API в `compileOnly` и `testImplementation`: плагин не включает его в себя, его предоставляет
Tazel.
|