Топаздокументация
Создание приложений

Цикл приложения

Выберите и пройдите путь платформенного файла, Python, веб-приложения или HTTP-сервиса в соответствии со способом поставки.

Переходите к этой странице после раздела Первое приложение. Этапы разработки являются общими, но способы поставки различаются. Выберите один необходимый целевой продукт вместо сборки всех вариантов подряд.

  • Платформенный файл подходит для автономного исполняемого файла, которому при развёртывании не требуется среда выполнения Топаза.
  • Python подходит, если в среде развёртывания уже установлен Python 3.11 или новее.
  • Web Application подходит, если Топаз управляет моделью браузерного приложения, сообщениями, обновлением состояния и отображением.
  • HTTP-сервис подходит для проверенного обработчика запросов, работающего под управлением супервизора и, для публичного трафика, за обратным прокси-сервером.

Raw Web и Worker предназначены для интеграции с существующей средой JavaScript. Они описаны в разделе WASM и песочница.

Общий цикл разработки

Начните с проверенного пакета из двух модулей. Манифест текущего платформенного пакета имеет следующее содержимое. Сохраните его под именем topaz.toml:

TOML
[package]
name = "task_summary"
version = "0.1.0"
language = "5.19"
entry = "src/main.tpz"

[build]
target = "native"
deterministic = true

[dependencies]
std = "5.19"

Вспомогательный модуль выполняет вычисления приложения:

TOPAZ
export function оставшиесяМинуты(значения: Array<int>) -> int {
  let mut итого = 0
  for значение in значения {
    итого += значение
  }
  итого
}

Входной модуль преобразует результат в наблюдаемую команду:

TOPAZ
import src.summary { оставшиесяМинуты }

export function main(аргументы: Array<string>, ввод: string) -> Result<int, string> {
  let минуты = оставшиесяМинуты([10, 25])
  print("remaining={минуты}")
  Ok(0)
}

Создайте topaz.lock один раз, затем выполняйте регулярную работу в следующем порядке:

BASH
topaz lock --root task-summary
topaz fmt --check --root task-summary
topaz check --root task-summary --locked
topaz test --root task-summary --locked
topaz run --root task-summary --locked

Команда fmt --check сообщает о расхождениях в форматировании, не изменяя файлы. При возникновении ошибок check и test останавливаются до формирования продукта. Исправьте первую диагностику Топаза и повторите ту же команду. Подробные сведения о коде диагностики можно получить с помощью команды topaz explain TPZ####.

Путь А: платформенное командное приложение или Python

Для платформенной сборки требуется инструментарий Rust, соответствующий текущей операционной системе и архитектуре. Для сборки под Python Rust не требуется, однако для готового продукта необходим Python 3.11 или новее.

Соберите только тот продукт, который планируете поставлять:

BASH
topaz build --release --root task-summary --locked --out-dir native-product
topaz build --target python --root task-summary --locked --out-dir python-product

Деревья релизных продуктов выглядят следующим образом:

Вывод
native-product/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── target
│   └── release
│       └── program[.exe]
└── topaz-artifact.json

python-product/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── program.py
├── topaz-artifact.json
└── topaz_py_rt.py

program[.exe] обозначает program в Unix и program.exe в Windows. Скопируйте выбранный каталог целиком в новое место и запускайте из его корня:

BASH
./target/release/program
python3 program.py

Первая команда относится к платформенному продукту, вторая — к продукту Python. Это взаимоисключающие варианты. Если приложение объявляет [capabilities.fs], разместите рядом с продуктом его каталог data/ и директории, доступные для записи, а корень продукта оставьте в качестве рабочего каталога. Данные приложения не включаются автоматически ни в платформенный продукт, ни в продукт Python.

Если для сборки не хватает инструментария Rust, установите подходящую версию Rust либо выберите вариант с Python. Если каталог вывода уже содержит другую цель или изменённый управляемый файл, сохраните его для анализа и соберите продукт в новом пустом каталоге.

Путь Б: управляемое веб-приложение

Для сборки Web Application требуется Rust с установленной целевой платформой wasm32-unknown-unknown. Не преобразуйте командный входной модуль, а создайте проверенный каркас:

BASH
topaz init --target web-app --root hello-web
topaz lock --root hello-web
topaz fmt --check --root hello-web
topaz check --root hello-web --locked
topaz test hello-web/tests/app.tpz --root hello-web --locked
topaz dev --root hello-web --port 8000
topaz build --root hello-web --locked --release --out-dir web-product

Созданный входной модуль использует проверяемый жизненный цикл:

TOPAZ
import std.dom { Html, WebAppEvent, WebAppStep, text }

export record Модель {
  сообщение: string,
}

export enum Сообщение {
  Готово,
}

export function init() -> WebAppStep<Модель, Сообщение> {
  WebAppStep { model: Модель { сообщение: "Hello from Topaz" }, commands: [] }
}

export function update(
  модель: Модель,
  сообщение: Сообщение,
  событие: WebAppEvent,
) -> WebAppStep<Модель, Сообщение> {
  WebAppStep { model: модель, commands: [] }
}

export function view(модель: Модель) -> Html<Сообщение> {
  text(модель.сообщение)
}

topaz dev — сервер разработки на локальном интерфейсе, который сохраняет последний исправный продукт при возникновении ошибок в коде. Это не промышленный сервер. Итоговый каталог содержит HTML, проверенную среду приложения, обёртку Raw Web, WASM, метаданные полномочий, объявленные стили и ресурсы, а также общие файлы лицензий и манифест артефакта. Скопируйте каталог целиком на статический сервер и раздавайте его по HTTP. Открытие модулей ES по протоколу file:// не является способом развёртывания.

Data Lens — поддерживаемый многомодульный пример этого пути.

Путь В: HTTP-сервис

Если продукт представляет собой обработчик запросов, а не команду или браузерный интерфейс, создайте каркас сервиса:

BASH
topaz init --target http-service --root hello-service
topaz lock --root hello-service
topaz fmt --check --root hello-service
topaz check --root hello-service --locked
topaz test --root hello-service --locked
topaz dev --root hello-service --port 8080
topaz build --root hello-service --locked --release --out-dir service-product

Граница обработчика является конкретной и синхронной:

TOPAZ
import std.http { HttpRequest, HttpResponse, text }

export function handle(запрос: HttpRequest) -> HttpResponse {
  if запрос.url.path() == "/health" {
    return text(200, "ok")
  }
  text(404, "not found")
}

Продукт сервиса содержит один платформенный исполняемый файл, встроенные ограниченные настройки, уведомления сторонних компонентов и общие файлы артефакта. По умолчанию он принимает соединения на локальном интерфейсе. Для использования другого адреса требуется передать явный аргумент процесса. Данный вариант не добавляет TLS, HTTP/2, исходящие сетевые запросы или универсальный веб-фреймворк.

Раздел HTTP-сервис завершает этот путь. В нём описаны бюджеты ресурсов, наблюдаемые ошибки, запуск без исходных текстов и восстановление после проблем развёртывания.

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