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

summaryrefslogtreecommitdiffhomepage
path: root/content/ru-RU/docs
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
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')
-rw-r--r--content/ru-RU/docs/1.getting-started/1.installation.md51
-rw-r--r--content/ru-RU/docs/1.getting-started/2.first-project.md165
-rw-r--r--content/ru-RU/docs/1.getting-started/3.releases.md35
-rw-r--r--content/ru-RU/docs/2.reference/1.commands.md119
-rw-r--r--content/ru-RU/docs/2.reference/2.module-file.md110
-rw-r--r--content/ru-RU/docs/2.reference/3.build-file.md143
-rw-r--r--content/ru-RU/docs/3.extending/1.plugins.md86
-rw-r--r--content/ru-RU/docs/4.internals/1.architecture.md50
8 files changed, 689 insertions, 70 deletions
diff --git a/content/ru-RU/docs/1.getting-started/1.installation.md b/content/ru-RU/docs/1.getting-started/1.installation.md
index a64ccd9..fc0aebd 100644
--- a/content/ru-RU/docs/1.getting-started/1.installation.md
+++ b/content/ru-RU/docs/1.getting-started/1.installation.md
@@ -1,42 +1,49 @@
---
title: Установка
-description: Установка Tazel и инструментов Tala, которые он запускает.
+description: Собрать Tazel из исходного кода и установить компиляторы и инструменты, которые он вызывает.
---
<!-- SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> -->
<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
-Tazel — программа на Kotlin для JVM, поэтому машине нужна среда Java 25 или новее. Сам он ничего не компилирует:
-`check`, `build`, `run` и `test` запускают Talac, `fmt` запускает talafmt, а `lint` — talalint.
+Tazel — программа на Kotlin для JVM. Сам он ничего не компилирует: он вызывает компиляторы и инструменты, найденные в
+`PATH`. Ни одна версия ещё не выпущена, поэтому Tazel собирается из исходного кода.
-## Сборка Tazel
+## Что нужно машине
+
+| Для чего | Установить |
+| --- | --- |
+| сам Tazel | JDK 25, например Eclipse Temurin 25 |
+| цели на C, C++, Objective-C и Objective-C++ | Clang или GCC; Clang собирает и для других троек |
+| цели на Zig и `zig cc` как компилятор C | Zig |
+| `tazel fmt` | clang-format для семейства C, `zig fmt` (входит в Zig) для Zig |
+| `tazel lint` | clang-tidy |
-Tazel собирается из исходного кода обёрткой Gradle, которой нужен JDK 25. `installDist` записывает запускающие файлы
-`tazel` и `tazel.bat` в `build/install/tazel/bin`. Добавьте эту папку в `PATH`.
+Каждый инструмент нужен только для команд и целей, которые им пользуются: модулю только на C++ Zig не нужен.
-```bash [Linux и macOS]
+## Сборка Tazel
+
+```bash
git clone https://github.com/Progmasoft/tazel.git
cd tazel
./gradlew installDist
```
-```powershell [Windows]
-git clone https://github.com/Progmasoft/tazel.git
-cd tazel
-.\gradlew.bat installDist
-```
+В Windows выполните в PowerShell `gradlew.bat installDist`. Программа находится в `build/install/tazel`: добавьте её
+каталог `bin` в `PATH` и проверьте:
-`tazel version` выводит установленную версию.
+```bash
+tazel version
+```
-## Инструменты Tala
+```text
+tazel 0.1.0
+```
-Каждый инструмент Tazel ищет через `TAZEL_TALAC`, `TAZEL_TALAFMT` или `TAZEL_TALALINT`, затем в своей установке, затем
-в `PATH`. У каждого инструмента свои выпуски:
+## Где Tazel ищет инструменты
-| Инструмент | Нужен для | Исходный код |
-| ---------- | ------------------------------- | ------------------------------------------------------------- |
-| Talac | `check`, `build`, `run`, `test` | [Progmasoft/tala](https://github.com/Progmasoft/tala) |
-| talafmt | `fmt` | [Progmasoft/talafmt](https://github.com/Progmasoft/talafmt) |
-| talalint | `lint` | [Progmasoft/talalint](https://github.com/Progmasoft/talalint) |
+Tazel берёт `clang`, `gcc`, `zig`, `clang-format` и `clang-tidy` из `PATH`. Цель может назвать свой компилятор:
+`compiler = Compiler.CLANG`, `Compiler.GCC` или `Compiler.ZIG_CC`; без этого Tazel берёт первый найденный, который
+собирает для тройки цели. Каждый инструмент читает свою конфигурацию, например `.clang-format` и `.clang-tidy`.
-Дальше: [первый проект](/docs/getting-started/first-project).
+Далее: [ваш первый проект](/docs/getting-started/first-project).
diff --git a/content/ru-RU/docs/1.getting-started/2.first-project.md b/content/ru-RU/docs/1.getting-started/2.first-project.md
index cc7d0aa..e56c014 100644
--- a/content/ru-RU/docs/1.getting-started/2.first-project.md
+++ b/content/ru-RU/docs/1.getting-started/2.first-project.md
@@ -1,60 +1,161 @@
---
-title: Первый проект
-description: Проект Tala в нескольких строках, его сборка, запуск, форматирование и проверка.
+title: Ваш первый проект
+description: Модуль с библиотекой на C, программой на C++ и тестом, собранный, запущенный и проверенный Tazel.
---
<!-- SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> -->
<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
-Проект — это папка с файлом проекта. Его исходники — файлы `.tala` в `Sources/`, а `entry` называет класс, чей
-`public static void Main()` запускает программу.
+Модуль — это каталог с `MODULE.kts` в корне. Каждый каталог ниже с `BUILD.kts` — пакет, и у каждой цели пакета есть
+метка: `//app/:greeter` — это цель `greeter` из `app/BUILD.kts`.
-```kotlin [BUILD.kts]
-project {
- name = "Example"
+```text
+greeter/
+├── MODULE.kts
+├── core/
+│ ├── BUILD.kts
+│ ├── include/core/greet.h
+│ └── src/greet.c
+├── app/
+│ ├── BUILD.kts
+│ └── src/main.cpp
+└── tests/
+ ├── BUILD.kts
+ └── greet_test.cpp
+```
+
+## Модуль
+
+```kotlin
+// MODULE.kts
+module {
+ name = "greeter"
+ version = "0.1.0"
}
+```
+
+## Библиотека на C
+
+```kotlin
+// core/BUILD.kts
+isPublic = true
+
+c.staticlib("core") {
+ sources(glob("src/*.c"))
+ headers("include")
+ standard = CStandard.C17
+}
+```
-sources {
- executable {
- entry = "Example.Program"
- }
+`isPublic = true` позволяет другим пакетам модуля зависеть от целей этого файла. `headers("include")` делает
+`#include <core/greet.h>` доступным в `core` и в каждой цели, которая от неё зависит.
+
+```c
+// core/include/core/greet.h
+#pragma once
+const char *greeting(void);
+```
+
+```c
+// core/src/greet.c
+#include <core/greet.h>
+const char *greeting(void) { return "Hello"; }
+```
+
+## Программа на C++
+
+```kotlin
+// app/BUILD.kts
+cpp.bin("greeter") {
+ sources(glob("src/*.cpp"))
+ depends("//core/:core")
+ standard = CppStandard.CPP20
}
```
-```tala [Sources/Main.tala]
-namespace Example;
+```cpp
+// app/src/main.cpp
+#include <cstdio>
+extern "C" {
+#include <core/greet.h>
+}
-public class Program {
- public static void Main() {
- Console.Println("Hello from Tala!");
- }
+int main(int argc, char **argv)
+{
+ std::printf("%s, %s!\n", greeting(), argc > 1 ? argv[1] : "world");
}
```
## Сборка и запуск
-```bash [terminal]
-tazel build
-tazel run -- first second
+```bash
+tazel build //app/:greeter
```
-`tazel build` записывает `build/debug/Example`, в Windows — `Example.exe`. `tazel run` собирает программу и запускает
-её; всё после `--` без разбора передаётся программе. Повторный `tazel build` без изменений сообщает, что цель актуальна,
-и не запускает компилятор.
+```text
+ Compiling //core/:core src/greet.c
+ Archiving //core/:core
+ Compiling //app/:greeter src/main.cpp
+ Linking //app/:greeter
+ Built 2 target(s) for x86_64-unknown-linux-gnu, debug; 4 command(s) run
+```
-## Форматирование и проверка
+Вторая сборка ничего не запускает, потому что ни один вход не изменился:
-```bash [terminal]
-tazel fmt -- --check
-tazel lint -- --fix
+```text
+ Built 2 target(s) for x86_64-unknown-linux-gnu, debug; 0 command(s) run
```
-Параметры после `--` передаются talafmt и talalint, поэтому `tazel fmt -- --check` только сообщает, а
-`tazel lint -- --fix` применяет исправления, какие может.
+`tazel run` собирает одну программу и запускает её; то, что идёт после `--`, передаётся программе:
+
+```bash
+tazel run //app/:greeter -- Ada
+```
+
+```text
+Hello, Ada!
+```
+
+Результаты лежат в `.tazel/out/<triple>/<mode>`, здесь `.tazel/out/x86_64-unknown-linux-gnu/debug`. `--release`
+собирает в режиме release.
+
+## Тест
+
+```kotlin
+// tests/BUILD.kts
+cpp.test("greet") {
+ sources("greet_test.cpp")
+ depends("//core/:core")
+}
+```
+
+```cpp
+// tests/greet_test.cpp
+#include <cstring>
+extern "C" {
+#include <core/greet.h>
+}
+
+int main() { return std::strcmp(greeting(), "Hello") == 0 ? 0 : 1; }
+```
+
+Тест проходит, если его программа завершается с кодом 0. `//tests/...` берёт каждую цель в `tests/` и ниже:
+
+```bash
+tazel test //tests/...
+```
+
+```text
+ Compiling //tests/:greet greet_test.cpp
+ Linking //tests/:greet
+ Built 2 target(s) for x86_64-unknown-linux-gnu, debug; 2 command(s) run
+ PASSED //tests/:greet in 0.0s
+ Tested 1 test(s): 1 passed, 0 failed
+```
::note
-ViGet не раздаёт пакеты Tala. Проект, объявляющий зависимость сборки, библиотечные цели и создание `.vipkg` отклоняются
-по имени с кодом выхода 1.
+Без метки `build`, `run` и `test` берут пакет текущего каталога. `//...` берёт весь модуль.
::
-Дальше: каждый блок [файла проекта](/docs/reference/project-file) и каждая [команда](/docs/reference/commands).
+Далее: [команды](/docs/reference/commands) и все настройки [MODULE.kts](/docs/reference/module-file) и
+[BUILD.kts](/docs/reference/build-file).
diff --git a/content/ru-RU/docs/1.getting-started/3.releases.md b/content/ru-RU/docs/1.getting-started/3.releases.md
index 0727e65..3ee0188 100644
--- a/content/ru-RU/docs/1.getting-started/3.releases.md
+++ b/content/ru-RU/docs/1.getting-started/3.releases.md
@@ -1,29 +1,32 @@
---
-title: Выпуски и поддержка
-description: Как нумеруется Tazel и сколько поддерживаются выпуски Rolling, LTS и ELTS.
+title: Выпуски
+description: Как Tazel нумерует версии и сколько поддерживается каждый вид выпуска.
---
<!-- SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> -->
<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
-Версия Tazel состоит из четырёх чисел: `MAJOR.SEMIMAJOR.MINOR.PATCH`, например `0.4.0.3`. У каждого выпуска есть тег
-`tazel-<version>` и примечания на [GitHub](https://github.com/Progmasoft/tazel/releases).
+Ни одна версия Tazel ещё не выпущена; первой будет 0.1.0. Что в неё уже вошло, описано в
+[разделе Unreleased журнала изменений](https://github.com/Progmasoft/tazel/blob/main/CHANGELOG.md#unreleased).
-## Три вида выпусков
+## Номера версий
+
+Версии следуют [Semantic Versioning](https://semver.org): `MAJOR.MINOR.PATCH`. Патч-выпуск исправляет, минорный —
+добавляет, а мажорный может изменить то, что работало раньше. Теги называются `tazel-0.1.0`, и опубликованный тег
+никогда не переносится.
+
+## Виды выпусков
| Вид | Поддержка | Какие выпуски |
| --- | --- | --- |
-| Rolling | 6 месяцев | каждый выпуск, который не LTS и не ELTS, и каждый выпуск до `1.0.0.0` |
-| LTS (Long-Term Support) | 5 лет | линия `A.0` каждого `MAJOR`, начиная с `1.0.0.0` |
-| ELTS (Extended Long-Term Support) | 12 лет | линия LTS для `MAJOR` 1, 4, 7 и каждого третьего после них |
-
-Срок считается от первого выпуска линии. Поддерживаемая линия получает исправления ошибок и проблем безопасности
-в виде новых выпусков `MINOR` и `PATCH`; новых возможностей она не получает, они приходят в выпусках Rolling.
+| Rolling | 6 месяцев | каждый выпуск до 1.0.0 и каждый выпуск вне линии LTS или ELTS |
+| LTS | 5 лет | линия MAJOR.0 остальных мажорных версий: 2.0.x, 3.0.x, 5.0.x, 6.0.x и далее |
+| ELTS | 12 лет | линия MAJOR.0 мажорных версий 1, 4, 7 и каждой третьей после них: 1.0.x, 4.0.x, 7.0.x |
-## Что выбрать
+Поддерживаемая линия получает только исправления, в виде своих патч-выпусков.
-- **Rolling** первым приносит каждую возможность. Берите новейший выпуск; предыдущий поддерживается ещё 6 месяцев.
-- **LTS** остаётся на одной линии 5 лет — для проектов, которые обновляются время от времени.
-- **ELTS** остаётся на одной линии 12 лет — для продуктов, которые долго поставляют программы на Tala.
+## Прежний Tazel
-Каждый выпуск Tazel до `1.0.0.0` — Rolling.
+Прежняя программа с тем же именем, версии с 0.1.0 по 0.4.0.3, находится в архиве
+[Progmasoft/tazel-legacy](https://github.com/Progmasoft/tazel-legacy). Её версии — не версии этого Tazel, который
+начинает снова с 0.1.0.
diff --git a/content/ru-RU/docs/2.reference/1.commands.md b/content/ru-RU/docs/2.reference/1.commands.md
new file mode 100644
index 0000000..ebc6b1b
--- /dev/null
+++ b/content/ru-RU/docs/2.reference/1.commands.md
@@ -0,0 +1,119 @@
+---
+title: Команды
+description: Каждая команда tazel, её параметры и метки, которые она принимает.
+---
+
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+```text
+tazel <command> [options] [labels]
+```
+
+| Команда | Что делает |
+| --- | --- |
+| `build` | собирает цели, например `tazel build //app/:greeter` или `tazel build //...` |
+| `run` | собирает одну цель `bin` и запускает её; то, что после `--`, передаётся программе |
+| `test` | собирает и запускает тестовые цели; то, что после `--`, передаётся каждому тесту |
+| `fmt` | форматирует исходники и заголовки целей с помощью clang-format и `zig fmt`; `--check` только сообщает |
+| `lint` | проверяет исходники семейства C с помощью clang-tidy; `--fix` применяет его исправления |
+| `custom` | запускает команду из `tazel_custom.txt` или выводит их список |
+| `version` | выводит версию Tazel |
+| `help` | выводит справку |
+
+Для опечатки в команде предлагается ближайшая команда.
+
+## Метки
+
+| Метка | Означает |
+| --- | --- |
+| `//:x` | цель `x` корневого `BUILD.kts` |
+| `//dir/:x` | цель `x` файла `dir/BUILD.kts` |
+| `:x` | цель `x` того же `BUILD.kts`, внутри файла проекта |
+| `@name//:x` | цель `x` зависимости `name`: её имя, псевдоним или имя её локального блока |
+| `//dir/...` | каждая цель `dir/BUILD.kts` и пакетов ниже |
+| `//...` | каждая цель модуля |
+
+Без метки `build`, `run` и `test` берут пакет текущего каталога. Шаблон не берёт тест с тегом `MANUAL`; такой тест
+запускается, только когда его назвали.
+
+## build, run и test
+
+| Параметр | Действие |
+| --- | --- |
+| `--release` | собирает в режиме release; без него — debug |
+| `--triple <triple>` | собирает для этой целевой тройки LLVM, например `aarch64-unknown-linux-gnu`; без него — для этой машины |
+
+Каждая цель собирается для каждой тройки, которую она называет и которую запрашивает команда, в режиме сборки команды.
+Результаты попадают в `.tazel/out/<triple>/<mode>`. Каждая компиляция, архивация, компоновка и сборка Zig запускается
+снова, только если изменились её командная строка, окружение или содержимое прочитанного файла либо записанный
+результат отсутствует или изменён.
+
+`tazel test` запускает каждый тест в его каталоге результатов, рядом с его данными, с его `args` и `env`. Тест
+проходит, если завершается с кодом 0. Тесты идут параллельно, кроме тестов с тегом `EXCLUSIVE`, которые идут
+поодиночке. Тест останавливается по тайм-ауту, повторяется до трёх раз при `flaky = true` и делится на `shards` с
+`TEST_TOTAL_SHARDS` и `TEST_SHARD_INDEX`. Прошедший тест не запускается снова, пока его программа, данные, аргументы
+и окружение те же, если у него нет тега `NO_CACHE`.
+
+## fmt и lint
+
+```bash
+tazel fmt //...
+tazel fmt --check //...
+tazel lint //...
+tazel lint --fix //app/...
+```
+
+`fmt` форматирует исходники, каталоги заголовков и текстовые заголовки выбранных целей с помощью clang-format (C, C++,
+Objective-C, Objective-C++) и `zig fmt` (Zig); `--check` сообщает, что не отформатировано, и ничего не меняет.
+
+`lint` записывает базу компиляции выбранных целей и их библиотек в
+`.tazel/out/<triple>/<mode>/compile_commands.json`, копирует её для редакторов в `.tazel/compile_commands.json` и
+запускает clang-tidy для каждой единицы трансляции семейства C. `--fix` применяет исправления по одной единице за раз.
+Цели на Zig пропускаются.
+
+Для обеих команд то, что после `--`, передаётся инструменту. Каждый инструмент читает свою конфигурацию, например
+`.clang-format` и `.clang-tidy`.
+
+## custom
+
+`tazel custom` запускает команды из `tazel_custom.txt` в корне модуля; `tazel custom` без аргументов выводит их
+список.
+
+```text
+# tazel_custom.txt
+format-check: ("tazel" "fmt" "--check" "//...");
+
+all:
+ ("tazel" "build" "//...")
+ ("tazel" "test" "//...");
+
+hello: s("echo hello from the shell");
+
+build with: ("tazel" "build" <1> <2>);
+```
+
+- Команда — это имя, `:`, один или несколько шагов и `;`. Имя может состоять из нескольких слов:
+ `tazel custom build with`.
+- Шаг `("program" "argument" ...)` запускает программу с этими аргументами. Строки пишутся в `"..."`, `'...'` или
+ `` `...` ``; экранирующих символов нет.
+- Шаг `s("...")` передаёт одну командную строку оболочке: `sh` в Linux и macOS, `cmd` в Windows.
+- `<1>`, `<2>` и далее передают аргументы командной строки по позиции; `<*>` передаёт все. `s(...)` аргументов не
+ принимает. `tazel custom first -- second` передаёт `second` команде `first`, если существует команда `first second`.
+- `#` начинает комментарий до конца строки; `<# ... #>` — многострочный комментарий.
+
+`tazel_options.txt` в корне модуля хранит параметры самого Tazel:
+
+```text
+sandboxing-with-microvm: false;
+```
+
+При `sandboxing-with-microvm: true` пользовательские команды должны идти в MicroVM, которую эта версия не запускает,
+поэтому они завершаются с ошибкой. `microvm-network`, `microvm-memory` и `microvm-cpus` настраивают эту MicroVM.
+
+## version и help
+
+```bash
+tazel version
+tazel help
+```
diff --git a/content/ru-RU/docs/2.reference/2.module-file.md b/content/ru-RU/docs/2.reference/2.module-file.md
new file mode 100644
index 0000000..e420be8
--- /dev/null
+++ b/content/ru-RU/docs/2.reference/2.module-file.md
@@ -0,0 +1,110 @@
+---
+title: MODULE.kts
+description: Файл в корне модуля: его имя, зависимости и то, как он собирается.
+---
+
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+У модуля один `MODULE.kts`, в его корне. Это скрипт Kotlin; `module { }` — единственный обязательный блок.
+
+```kotlin
+module {
+ name = "greeter"
+ version = "1.2.0"
+ description = "Greets people."
+ authors("Ada Lovelace", "Alan Turing")
+ license = "MIT"
+}
+
+dependencies {
+ implementation("Publisher") {
+ name = "toml"
+ version = "1.0.0"
+ }
+ testImplementation("Progmasoft") {
+ name = "catch3"
+ version = "0.4.0"
+ }
+ localImplementation {
+ name = "libs"
+ include(glob("libs/*.vipkg"))
+ }
+}
+
+execution {
+ jobs = 8
+ keepGoing = false
+}
+```
+
+## module
+
+| Настройка | Значение |
+| --- | --- |
+| `name` | имя модуля; обязательно |
+| `version` | семантическая версия, например `1.2.0` |
+| `description` | одно предложение о модуле |
+| `authors(...)` | его авторы |
+| `license` | выражение лицензии SPDX, например `MIT` или `Apache-2.0 OR MIT` |
+
+## dependencies
+
+| Блок | Даёт |
+| --- | --- |
+| `implementation("Publisher") { name; version; alias }` | пакет из ViGet, от которого может зависеть любая цель |
+| `testImplementation("Publisher") { ... }` | то же, только для тестовых целей |
+| `localImplementation { name; include(...) }` | пакеты из файлов `.vipkg` модуля |
+| `localTestImplementation { ... }` | то же, только для тестовых целей |
+
+Издатель — это [Progmasoft Account](https://progmasoft.com). Цель называет цель зависимости как `@name//:x`, где
+`name` — это `name` зависимости, её `alias` или `name` локального блока. Локальный блок, `include` которого берёт
+несколько пакетов, даёт им одно имя; одно и то же имя цели в двух из них — ошибка.
+
+::note
+Эта версия Tazel читает зависимости и проверяет метки, которые их называют; пакеты из ViGet она не загружает.
+Версии, которые разрешает модуль, фиксируются в `LOCK.sqlite3` в его корне — файле блокировки Tazel, который эта
+версия не записывает.
+::
+
+## viget
+
+```kotlin
+viget {
+ push = true
+ pushTarget("//core/:core", "//app/:greeter")
+ exclude(glob("docs/**"))
+}
+```
+
+`pushTarget` называет цели, которые содержит пакет модуля; в их `BUILD.kts` должно быть `isPublic = true`. `exclude`
+исключает файлы из пакета. По умолчанию `push` — `false`.
+
+## cache
+
+```kotlin
+cache {
+ local = true
+ keep = 8
+ remote("https://cache.example.com") {
+ read = true
+ write = false
+ token = env("TAZEL_CACHE_TOKEN")
+ }
+}
+```
+
+`local` (по умолчанию `true`) и `keep` (сколько результатов хранить на цель, по умолчанию `8`) описывают локальный
+кэш; `remote(...)` добавляет общий, с `read` (по умолчанию `true`), `write` (по умолчанию `false`), `token`,
+`publicKey` и `signingKey`. `env("NAME")` читает переменную окружения, чтобы секреты не попадали в файл.
+
+## execution
+
+| Настройка | По умолчанию | Действие |
+| --- | --- | --- |
+| `jobs` | число процессоров | сколько команд идёт одновременно |
+| `memory` | без ограничения | ограничение вроде `16.gigabytes` |
+| `keepGoing` | `false` | после ошибки запускать команды, которые от неё не зависят |
+| `remote(url) { token }` | нет | машина, которая выполняет команды |
+
+Эта версия Tazel учитывает `jobs` и `keepGoing`; остальные настройки `cache` и `execution` читаются и проверяются.
diff --git a/content/ru-RU/docs/2.reference/3.build-file.md b/content/ru-RU/docs/2.reference/3.build-file.md
new file mode 100644
index 0000000..1201412
--- /dev/null
+++ b/content/ru-RU/docs/2.reference/3.build-file.md
@@ -0,0 +1,143 @@
+---
+title: BUILD.kts
+description: Цели пакета и все настройки, которые может иметь цель.
+---
+
+<!-- SPDX-FileCopyrightText: 2026 Progmasoft <[email protected]> -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+У каждого пакета один `BUILD.kts` — скрипт Kotlin, объявляющий его цели. Настройка, которой нет у языка или вида
+цели, — ошибка компиляции файла, поэтому редактор показывает её ещё до запуска Tazel.
+
+## Цели
+
+| Язык | Исходники | Виды |
+| --- | --- | --- |
+| `c` | `.c` | `bin`, `staticlib`, `sharedlib`, `test` |
+| `cpp` | `.cpp`, `.cc`, `.cxx` | те же |
+| `objc` | `.m` | те же |
+| `objcpp` | `.mm` | те же |
+| `zig` | корневой файл `.zig` | те же |
+
+```kotlin
+c.staticlib("core") { ... } // //core/:core
+cpp.bin("greeter") { ... } // a program
+zig.test("tool") { ... } // a test
+```
+
+У цели один язык. Цели на разных языках связываются через `depends`: программа на C++ может зависеть от библиотеки на
+C и от библиотеки на Zig, которая предоставляет заголовок C.
+
+## Видимость
+
+`isPublic` в начале файла по умолчанию `false`: от его целей могут зависеть только цели того же файла.
+`isPublic = true` открывает их другим пакетам модуля и модулям, которые от него зависят.
+
+## Любая цель
+
+| Настройка | Действие |
+| --- | --- |
+| `sources(...)` | исходные файлы: пути или `glob("src/**/*.c")` |
+| `depends(...)` | метки целей, которые она использует |
+| `targetTriple(...)` | целевые тройки LLVM, для которых она собирается; по умолчанию — тройка этой машины |
+| `data(...)` | файлы, копируемые рядом с программой для `run` и `test` |
+| `outputName` | имя файла результата; по умолчанию — имя цели |
+
+## Тройки, режимы сборки и условия
+
+Блок цели выполняется один раз для каждой тройки и каждого режима сборки. `OS` и `ARCH` берутся из тройки,
+`BUILD_MODE` — из команды, поэтому условие — обычный Kotlin:
+
+```kotlin
+cpp.bin("greeter") {
+ sources(glob("src/**/*.cpp"))
+ targetTriple("x86_64-unknown-linux-gnu", "aarch64-apple-darwin", "x86_64-pc-windows-msvc")
+
+ when (BUILD_MODE) {
+ BuildMode.DEBUG -> sanitize(Sanitizer.ADDRESS, Sanitizer.UNDEFINED)
+ BuildMode.RELEASE -> {
+ optimize = Optimize.SPEED
+ lto = Lto.THIN
+ strip = true
+ }
+ }
+ when (OS) {
+ Os.WINDOWS -> links("ws2_32")
+ Os.LINUX -> links("dl")
+ Os.MACOS -> frameworks("CoreFoundation")
+ else -> {}
+ }
+}
+```
+
+## Цели на C, C++, Objective-C и Objective-C++
+
+| Настройка | Значения и умолчание |
+| --- | --- |
+| `exclude(...)` | исходники, которые исключаются |
+| `headers(...)` | каталоги заголовков, видимые здесь и зависимым целям |
+| `privateHeaders(...)` | каталоги заголовков, видимые только здесь |
+| `textualHeaders(...)` | заголовки, которые включаются, но никогда не компилируются отдельно |
+| `includePrefix`, `stripIncludePrefix` | меняют путь, по которому зависимые цели включают заголовки |
+| `compiler` | `Compiler.CLANG`, `GCC`, `ZIG_CC`, `MSVC`, `CLANG_CL`; по умолчанию — первый найденный, который собирает для тройки. Эта версия собирает с Clang, GCC и `zig cc`; `MSVC` и `CLANG_CL` останавливают сборку с ошибкой |
+| `standard` | C: от `CStandard.C89` до `C23`; C++ и Objective-C++: от `CppStandard.CPP11` до `CPP26`; по умолчанию — новейший, который поддерживает компилятор |
+| `gnuExtensions` | по умолчанию `false` |
+| `defines(...)`, `privateDefines(...)` | макросы для этой цели и зависимых или только для этой |
+| `flags(...)` | дополнительные флаги компилятора |
+| `warnings` | `Warnings.ALL`, `DEFAULT`, `NONE`; по умолчанию `DEFAULT` |
+| `warningsAsErrors` | по умолчанию `false` |
+| `precompiledHeader` | заголовок, компилируемый один раз |
+| `debugInfo` | `DebugInfo.NONE`, `FULL`, `SPLIT`; по умолчанию `FULL` в debug и `NONE` в release |
+| `optimize` | `Optimize.NONE`, `SIZE`, `SPEED`; по умолчанию `NONE` в debug и `SPEED` в release |
+| `lto` | `Lto.NONE`, `THIN`, `FULL`; по умолчанию `NONE` |
+| `strip` | по умолчанию `false` |
+| `sanitize(...)` | `Sanitizer.ADDRESS`, `UNDEFINED`, `THREAD`, `MEMORY`, `LEAK` |
+| `links(...)`, `linkFlags(...)` | библиотеки и флаги для компоновщика |
+| `frameworks(...)` | фреймворки Apple |
+| `arc` | только Objective-C и Objective-C++; по умолчанию `true` |
+
+### По видам
+
+| Настройка | Виды | Действие |
+| --- | --- | --- |
+| `args(...)`, `env(...)` | `bin`, `test` | что `run` и `test` передают программе |
+| `rpath(...)`, `linkerScript`, `resources(...)` | `bin`, `sharedlib`, `test` | компоновка |
+| `subsystem` | `bin` | `Subsystem.CONSOLE` или `WINDOWS` в Windows |
+| `bundle { identifier; infoPlist; resources(...); codesignIdentity }` | `bin` на Objective-C | пакет `.app` |
+| `pic`, `alwaysLink` | `staticlib` | позиционно-независимый код, компоновка всего архива |
+| `exports(...)`, `soVersion`, `defFile` | `sharedlib` | символы и версия библиотеки |
+
+## Цели на Zig
+
+У целей на Zig нет компилятора и стандарта: `sources` называет корневой файл, а `optimize` принимает
+`ZigOptimize.SAFE`, `SPEED` или `SIZE`. Библиотека на Zig может предоставить заголовок C через `headers(...)`.
+
+```kotlin
+zig.staticlib("checksum") {
+ sources("checksum.zig")
+ headers("include")
+}
+```
+
+## Тесты
+
+Тест собирается как программа и проходит, если завершается с кодом 0.
+
+| Настройка | Значения и умолчание |
+| --- | --- |
+| `size` | `TestSize.SMALL`, `MEDIUM`, `LARGE`, `ENORMOUS`; по умолчанию `MEDIUM`; задаёт тайм-аут: 1, 5, 15 или 60 минут |
+| `timeout` | длительность вроде `2.minutes`; по умолчанию — из `size` |
+| `flaky` | `true`: неудача повторяется до трёх раз |
+| `shards` | разбить на столько запусков, каждому сообщаются `TEST_TOTAL_SHARDS` и `TEST_SHARD_INDEX`; по умолчанию `1` |
+| `tags(...)` | `TestTag.MANUAL` (только когда назван), `EXCLUSIVE` (отдельно), `LOCAL`, `NO_CACHE` (всегда) |
+| `linkStatic` | тесты семейства C; по умолчанию `true` |
+
+```kotlin
+cpp.test("unit") {
+ sources(glob("*_test.cpp"))
+ depends("//core/:core")
+ data(glob("fixtures/*"))
+ size = TestSize.SMALL
+ shards = 4
+}
+```
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` соде�