diff options
| author | Leitwolf | 2026-11-16 14:49:23 +0300 |
|---|---|---|
| committer | GitHub | 2026-11-16 14:49:23 +0300 |
| commit | 324048967d1fb198e3489b1722ca1ff317338550 (patch) | |
| tree | e270ad6dc86200cc79cbdccfa1ef6de1da8aff0d /content/ru-RU | |
| parent | 45c1bb14326cbee8fe57c6f639550e8eadd81f0a (diff) | |
| parent | 4ee77681379619b3fab7b8b33446a67164216cc8 (diff) | |
| download | tazel.net-main.tar.gz | |
Rewrite the site for the Tazel of C, C++, Objective-C, Objective-C++ and Zig
Diffstat (limited to 'content/ru-RU')
| -rw-r--r-- | content/ru-RU/docs/1.getting-started/1.installation.md | 51 | ||||
| -rw-r--r-- | content/ru-RU/docs/1.getting-started/2.first-project.md | 165 | ||||
| -rw-r--r-- | content/ru-RU/docs/1.getting-started/3.releases.md | 35 | ||||
| -rw-r--r-- | content/ru-RU/docs/2.reference/1.commands.md | 119 | ||||
| -rw-r--r-- | content/ru-RU/docs/2.reference/2.module-file.md | 110 | ||||
| -rw-r--r-- | content/ru-RU/docs/2.reference/3.build-file.md | 143 | ||||
| -rw-r--r-- | content/ru-RU/docs/3.extending/1.plugins.md | 86 | ||||
| -rw-r--r-- | content/ru-RU/docs/4.internals/1.architecture.md | 50 |
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` содержит пакет `com.progmasoft.api.tazel.dsl.plugin`. + +| Тип | Что это | |