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

summaryrefslogtreecommitdiffhomepage
path: root/content/ru-RU/docs/3.extending
diff options
context:
space:
mode:
authorLeitwolf2026-11-16 14:49:23 +0300
committerGitHub2026-11-16 14:49:23 +0300
commit324048967d1fb198e3489b1722ca1ff317338550 (patch)
treee270ad6dc86200cc79cbdccfa1ef6de1da8aff0d /content/ru-RU/docs/3.extending
parent45c1bb14326cbee8fe57c6f639550e8eadd81f0a (diff)
parent4ee77681379619b3fab7b8b33446a67164216cc8 (diff)
downloadtazel.net-main.tar.gz
Merge pull request #10 from Progmasoft/content/new-tazelHEADmain
Rewrite the site for the Tazel of C, C++, Objective-C, Objective-C++ and Zig
Diffstat (limited to 'content/ru-RU/docs/3.extending')
-rw-r--r--content/ru-RU/docs/3.extending/1.plugins.md86
1 files changed, 86 insertions, 0 deletions
diff --git a/content/ru-RU/docs/3.extending/1.plugins.md b/content/ru-RU/docs/3.extending/1.plugins.md
new file mode 100644
index 0000000..00029b0
--- /dev/null
+++ b/content/ru-RU/docs/3.extending/1.plugins.md
@@ -0,0 +1,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.