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/docs/2.reference | |
| 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/docs/2.reference')
| -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 |
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 +} +``` |