Топаздокументация
Инструменты и выполнение

CLI и диагностика

Подберите команду Топаза под задачу и изучите сценарии успешного выполнения, ошибок и восстановления.

CLI применяет одинаковые разбор, разрешение модулей и статическую проверку к отдельному файлу и к пакету. Команда выбирает действие после прохождения этого общего барьера.

Форматирование перед проверкой

При рецензировании кода и в сценариях автоматизации используйте fmt --check. Команда сообщает обо всех файлах, отклоняющихся от канонического форматирования, завершается с ненулевым кодом и ничего не записывает.

BASH
topaz fmt --check --root my-app
topaz fmt --root my-app

Вторая команда применяет форматирование. После неё повторите первую. В пакетном режиме пропускаются скопированные в проект зависимости и результаты сборки.

Проверка без запуска

BASH
topaz check main.tpz
topaz check --root my-app --locked
topaz check --format json main.tpz

Успешная проверка завершается с кодом 0. Диагностика содержит указание на место в исходном коде, стабильный код TPZ####, краткую формулировку и необходимые подробности. Формат JSON выводит стабильные данные для инструментов. Пользовательский код не запускается, а артефакт развёртывания не записывается.

BASH
topaz explain TPZ5021
topaz explain TPZ5021 --json

Исправьте первую диагностику и снова запустите check. Последующие ошибки могут быть её следствием. explain раскрывает известный код ошибки, но не меняет исходный код.

Сужение проверки до одного профиля применения

Команда check принимает --profile и сужает канонический Топаз до меньшего исполняемого профиля применения. Программа, прошедшая обычную проверку, всё равно может не пройти проверку по профилю.

BASH
topaz check --profile agent-pack main.tpz
topaz check --profile test-profile tests/plan.tpz

agent-pack принимает только те формы, которым место в обычном прикладном коде. Он отклоняет assert, импорт std.test, члены Test.* и композицию функций >>. Всё это относится к тестам или к уровню спецификации, а не к поставляемому коду. Единственное отличие test-profile состоит в том, что он разрешает каноническую свободную функцию assert(...). Композицию и поверхность тестового фреймворка он отклоняет так же. Профиль Bootstrap для исходников ядра компилятора описан в разделе Состояние инструментария.

Диагностика для человека несёт стабильный код TPZ5801 и пометку правила, например agent-pack/no-composition. При --format json в stderr попадает по одному объекту topaz.profile-diagnostic/v1 на каждую диагностику, а в stdout — одна сводка topaz.profile-check/v1. Флаг --profile относится только к check. Он требует канонического Топаза текущего режима и не сочетается с --exports-json.

Тестирование и запуск

BASH
topaz test --root my-app --locked
topaz test tests/summary.tpz --root my-app --locked
topaz run --root my-app --locked
topaz run main.tpz -- arg1 arg2

test использует проверенную детерминированную тестовую среду. Неудачное утверждение, статическая диагностика или ошибка среды выполнения дают ненулевой код. Выбранный с --root тестовый файл сохраняет манифест, файл блокировки, модули и зависимости пакета.

run выполняет проверенный командный вход в интерпретаторе. Аргументы после -- передаются в main. Пакеты Web Application и HTTP используют для разработки на адресе обратной петли команду topaz dev, потому что их наблюдаемый продукт — браузерное приложение или сервис, а не команда.

Сборка одной цели поставки

BASH
topaz build main.tpz --out-dir native-product
topaz build --target python --root my-app --locked --out-dir python-product
topaz build --root my-app --locked --release --out-dir product

build сначала проверяет программу, затем записывает запрошенный управляемый продукт. Для платформенной, браузерной и HTTP-сборки нужны соответствующие внешние компоненты Rust. Python требуется при запуске Python-продукта. Статическая ошибка останавливает создание артефакта. Ошибка внешнего инструмента сообщается после основного этапа Топаза и также даёт ненулевой код.

Если каталог вывода содержит другую цель, неверный манифест артефакта или изменённые управляемые байты, Топаз не угадывает владельца. Сохраните каталог для анализа и выберите новый пустой --out-dir.

Границы пакета и машинного интерфейса

Если опустить входной файл и передать --root, используется точка входа из topaz.toml. --locked требует соответствия текущего манифеста и локального содержимого зависимостей файлу topaz.lock. Аргументы программы всегда идут после --.

--unchecked — обходной путь для исследования компилятора, а не обычная команда приложения. Он снимает статический барьер и не должен использоваться, чтобы представить неудачную проверенную сборку успешной.

Связанная документация