Skip to content

tt wasm

Commands for tarantool-wasm, the Tarantool module that runs WebAssembly components (github.com/tarantool/tarantool-wasm-rs): prepare puts the runtime, tarawasm and the toolchains in place, new adds a component, status reports what a build lacks, and rock packs the rocks of a release for a rock server. They are a stopgap until tt builds the components itself: the components are built by tarawasm for now.

Usage

tt wasm
tt wasm [flags] <command> [command flags]

Commands

  • tt wasm new - Add a WebAssembly component to the package
  • tt wasm prepare - Add the wasm runtime, tarawasm and the toolchains to the project
  • tt wasm rock - Pack the rocks of a release for a rock server
  • tt wasm status - Show how far the project is prepared, changing nothing

tt wasm new

Add a WebAssembly component to the package of the project, which tt wasm prepare has prepared.

tarawasm creates the component in the directory NAME (or --dir), on the SDK of the wasm release the package declares, and a .gitignore keeps what it generates out of git. The manifest declares the component, built by tarawasm all into the namespace of the package:

[components.NAME]
path = "NAME"
include = ["dist/NAME.wasm"]

[components.NAME.build]
backend = "shell"
command = "tarawasm"
args = ["all"]
incremental = true

The WIT world of the component, and the file it builds, are named after it unless --world names them; the build is skipped while its sources have not changed.

The toolchain of a language is put in place for the language of each component tarawasm builds, and for --lang. tt installs wasm-tools, wkg and, for Python, componentize-py into the project, each checked against the sha256 tt holds it to. The other tools - python3, Go and TinyGo, Rust and cargo-component, Node and jco, the wasi-sdk and wit-bindgen, .NET - are the user's to install: tt checks their versions, says which to install, and installs nothing into the system.

Usage

tt wasm new NAME [flags]

Flags

  • --dir string - the directory of the component (default NAME)
  • --lang string - the language of the component: c, csharp, go, js, python, rust
  • --registry stringArray - rock server to use instead of the configured ones: an http(s) URL or a local directory; repeat to give an ordered list (overrides TT_REGISTRIES and [platform].registries)
  • --template string - start from a template: http (an HTTP API over a space) or call (an exported function); Python only
  • --world string - the name of its WIT world (default app)

Examples

# A component in Python, in the directory router.
$ tt wasm new router --lang python

# An HTTP API over a space, served by the component itself.
$ tt wasm new router --lang python --template http

# Elsewhere, with a world of its own name.
$ tt wasm new api --lang rust --dir wasm/api --world api

tt wasm prepare

Prepare the project for tarantool-wasm.

The manifest declares the binary rock wasm of the release, its native module, from the rock server --rock-server names:

wasm = { version = "<release>", registry = "<rock server>" }

and the lock is re-resolved, so the next tt package build installs it where require('wasm') finds it. A declaration already there is left as it is. The default server is the rock index of tarantool-contrib/rocks-repo,

https://raw.githubusercontent.com/tarantool-contrib/rocks-repo/index/

which serves the rock of every platform with its sha256, so the lock pins them all; another may be one tt wasm rock packs. Any version a server serves is taken.

With --from, a local build of the module is packed as the rock of this host into .tarantool/registry instead, and the dependency names that directory; --from packs the releases tt knows: 0.1.0.

tarawasm, which builds the components for now, is installed into a virtual environment under .tarantool (Python 3.10 or newer) and linked as .tarantool/bin/tarawasm. Component builds find programs there by name, and .env/activate.sh puts the directory on the shell's PATH.

The toolchain of a language is put in place for the language of each component tarawasm builds, and for --lang. tt installs wasm-tools, wkg and, for Python, componentize-py into the project, each checked against the sha256 tt holds it to. The other tools - python3, Go and TinyGo, Rust and cargo-component, Node and jco, the wasi-sdk and wit-bindgen, .NET - are the user's to install: tt checks their versions, says which to install, and installs nothing into the system.

The SDK of each component is restored as the component's lock pins it, and must be of the release prepared.

The registry and .tarantool are for this host and are not meant to be committed: after a checkout, run tt wasm prepare again.

Usage

tt wasm prepare [flags]

Flags

  • --from string - pack this local build of the module into .tarantool/registry and declare the rock from there
  • --lang string - put the toolchain of a language in place too: c, csharp, go, js, python, rust
  • --no-tarawasm - do not install tarawasm
  • --python string - Python to install tarawasm with (default python3)
  • --registry stringArray - rock server to use instead of the configured ones: an http(s) URL or a local directory; repeat to give an ordered list (overrides TT_REGISTRIES and [platform].registries)
  • --reinstall - install tarawasm anew
  • --rock-server string - the rock server to declare the rock from: a URL or a directory relative to the project (default the rock index of tarantool-contrib/rocks-repo)
  • --tarawasm string - what pip installs instead of the tarawasm tt pins (a version, a URL, a path)
  • --version string - tarantool-wasm release: any the rock server serves, or one tt knows with --from (default 0.1.0)

Examples

# Prepare the package in the current directory for Python components.
$ tt wasm prepare --lang python
$ tt wasm new router --lang python

# After a checkout: the runtime, tarawasm, the toolchains and the SDKs
# of the components.
$ tt wasm prepare

# Add the runtime only: the components are built some other way.
$ tt wasm prepare --no-tarawasm

# A local build of the module.
$ tt wasm prepare --from target/release/libtarantool_wasm_rs.so

tt wasm rock

Pack the wasm rock of every platform of a tarantool-wasm release into --out, with the LuaRocks manifest and the rock index that make the directory a rock server, the index pinning the sha256 of every rock in the lock of a project that depends on it. Serve it, or upload its files next to the assets of the release, and declare the dependency from it with tt wasm prepare --rock-server: then every machine gets the build of its own, and an archive packed --without-deps installs anywhere. The assets are checked against the sha256 tt holds the release to. With --from, pack the one local build of the module as the rock of --arch (default this host's) and keep the rocks already in --out: run it once for the build of each platform.

Usage

tt wasm rock [flags]

Flags

  • --arch string - the LuaRocks arch of the build --from names (linux-x86_64, macosx-aarch64; default this host's)
  • --from string - pack this local build of the module instead of downloading the assets
  • --out string - the directory to pack the rocks into
  • --version string - tarantool-wasm release (default 0.1.0)

Examples

# The rocks of 0.1.0, for the assets of the release on GitHub.
$ tt wasm rock --out dist/rocks
$ gh release upload v0.1.0 dist/rocks/*
$ tt wasm prepare --rock-server \
    https://github.com/tarantool/tarantool-wasm-rs/releases/download/v0.1.0/

# Local builds, one per platform.
$ tt wasm rock --from target/release/libtarantool_wasm_rs.so \
    --out dist/rocks
$ tt wasm rock --arch macosx-aarch64 --out dist/rocks \
    --from target/release/libtarantool_wasm_rs.dylib

tt wasm status

Show what tt wasm prepare put in place and tt package build needs: the wasm rock the package declares and its build for this host, tarawasm, the components tarawasm builds with the SDK each pins, and the toolchain of their languages. Nothing is installed or changed. Anything missing is listed, and the command fails, as a check in CI does.

Usage

tt wasm status