Топаздокументация
Сборка и поставка

WASM и песочница

Соберите пакет WASM, вызовите функцию Топаза из JavaScript и определите, когда нужен Worker.

Соберите браузерный пакет и вызовите функцию Топаза из JavaScript с аргументами 45 и 20. Пример вернёт оставшееся время 25 и покажет, как читать результат с указанием типа.

Для локальной сборки нужны CLI Топаза, Rust с Cargo и wasm32-unknown-unknown. Пример JavaScript запускается в Node.js. Готовый браузерный пакет работает без Топаза и Rust.

Запустите исходный код в песочнице

В песочнице можно редактировать, проверять и запускать Топаз в браузере без установки CLI. Она загружает WASM компилятора и интерпретатора внутри Worker. Для вызова функций Топаза из собственного приложения JavaScript соберите пакет Web по примеру ниже.

Соберите пакет Web

В новом каталоге сохраните всю программу как main.tpz.

TOPAZ
export function остаток(всего: int, потрачено: int) -> int {
    всего - потрачено
}

Выполните сборку из этого каталога.

BASH
topaz build --target web main.tpz --release --out-dir web-product

В конце сборка выводит пути к topaz-web.wasm и его загрузчику topaz-web.js. Каталог web-product содержит topaz-web.js, topaz-web.d.ts, topaz-web.wasm и общие файлы. Ваше приложение JavaScript создаёт интерфейс и вызывает экспортированные функции через сгенерированный модуль.

Вызовите функцию из JavaScript

Сохраните этот package.json рядом с main.tpz, чтобы Node.js читал созданный файл .js как модуль ES.

JSON
{ "type": "module" }

Сохраните следующий файл как call.mjs в том же каталоге.

JAVASCRIPT
import { readFile } from 'node:fs/promises';
import { instantiateTopaz } from './web-product/topaz-web.js';

const wasm = await readFile(
  new URL('./web-product/topaz-web.wasm', import.meta.url)
);
const app = await instantiateTopaz(wasm);
const result = app.exports.остаток(
  { $: 'int', value: '45' },
  { $: 'int', value: '20' }
);
console.log(JSON.stringify(result));

Запустите файл JavaScript из каталога с main.tpz.

BASH
node call.mjs

Вызов выдаёт следующий результат.

Вывод
{"status":"ok","value":{"$":"int","value":"25"}}

Значение status: "ok" означает успешный вызов. Результат содержит целое число Топаза в виде десятичной строки "25". Каждый аргумент также содержит метку int и десятичную строку. Такой формат сохраняет значение целого числа при передаче через JavaScript.

Созданный topaz-web.d.ts описывает этот формат аргументов и результатов, называемый ABI. Проверяйте status перед чтением value. Результат fault содержит код ошибки, сообщение и диапазон исходного кода. Результат error содержит сообщение. Исправьте имя экспорта, аргументы или указанный исходный код Топаза перед повторным вызовом.

В браузере раздавайте весь продукт по HTTP. Импортируйте instantiateTopaz в модульном скрипте и передайте ему URL файла topaz-web.wasm. Экспортированная функция принимает аргументы с теми же метками типов. Браузеры не поддерживают прямую загрузку этого пакета через file://.

Выполняйте вызовы в Worker вне главного потока

Соберите тот же main.tpz для Worker, если вызовы должны выполняться вне главного потока браузера.

BASH
topaz build main.tpz --target web-worker --release --out-dir worker-product

К файлам Web добавляются topaz-web-worker.js и topaz-web-worker-client.js. Клиент передаёт запросы и ответы в том же формате аргументов и результатов. Вызовы выполняются асинхронно. Интерфейс и разрешения по-прежнему задаёт ваше приложение JavaScript. Worker не предоставляет дополнительных полномочий.

Исправьте ошибки загрузки и сборки

ПроблемаДействие
Отсутствует цель Rust для WASMУстановите wasm32-unknown-unknown в инструментарий Rust, который использует сборка
Браузер сообщает о несовпадении идентификаторов среды и файлов выполненияРазверните весь каталог одной сборки и храните его JavaScript вместе с WASM
Изменены управляемые файлы каталога выводаСохраните каталог для изучения и выберите новый пустой --out-dir

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