Read-only mirrors. Development, issues and pull requests are on GitHub.

summaryrefslogtreecommitdiffhomepage
path: root/content/ru-RU/docs/3.extending/1.plugins.md
blob: 00029b07ada62709e8be94db0c69fcff781ca9df (plain)
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.