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

summaryrefslogtreecommitdiffhomepage
path: root/content/ru-RU/docs/2.reference
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/2.reference
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/2.reference')
-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
3 files changed, 372 insertions, 0 deletions
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
+}
+```