Skip to content

Building

nomi build <file> [-o <out>] [--target <goos>/<goarch>] writes one executable: the nomi-vm binary with the compiled program appended to it, the way deno compile and bun build --compile work. At startup nomi-vm reads the program from its own file and runs main exactly as nomi run does: the same arguments, standard input, signal handling, output and exit status. It skips the front end, so a hello-world program starts in a few milliseconds, and then runs on the same VM at nomi run speed. It is not native code.

nomi build refuses what nomi run would refuse, with the same text, and writes nothing: a front-end error, or an error at each piece of code the compiler cannot compile. It also refuses:

  • a file without fn main, which has nothing to build, unless it has an export fn and the target is wasip1/wasm (below);
  • a program with a todo or a dbg in any of its files, whether or not a run would reach it (spec §11 Unwritten code: todo and spec §8 dbg). It prints one list of every todo and every dbg, in file and source order, under one header that counts them (nomi build: 2 todos remain:, or 1 todo and 2 dbgs remain: with both). Each line is the position and the item: a todo with its reason, a dbg with its operand cut after 40 characters with ..., and |> dbg for a pipe stage.
nomi build: 1 todo and 2 dbgs remain:
  main.nomi:2:5 todo "parse the header"
  main.nomi:7:5 dbg total + 1000000000 + 2000000000 + 300000...
  main.nomi:8:18 |> dbg

--target, or GOOS/GOARCH in the environment, picks the platform. nomi-vm comes from, in order:

  1. nomi-vm beside nomi (or beside the file a symlinked nomi resolves to), built for the target. Every release archive ships one.
  2. A source checkout of the compiler: nomi-vm is built with go build and cached. This is how go install and a development tree work, with no release involved.
  3. A nomi-vm downloaded earlier for this release and target.
  4. Download: the target’s archive from the release this nomi was cut as, verified against the release’s checksum file, with only nomi-vm extracted and cached. nomi build prints the URL it downloads, and with no network the error names it.

A prebuilt nomi-vm must come from the same commit as nomi. Both carry it in their build information, and nomi build refuses a nomi-vm from another commit. So a release builds executables for every platform with no Go toolchain, and a built binary needs nothing at all.

A project whose Go bindings are all first-party lib/ modules’ at the release’s commit is appended to nomi-vm-lib, which links them (Go bindings), with no Go toolchain, for each native platform and js/wasm.

Two kinds of program still need Go, which builds their own nomi-vm from the compiler module at the release’s version:

  • a project with any other Go FFI binding, or a lib/ module at another commit, whose nomi-vm links them;
  • a program importing std::compiler, whose nomi-vm links the front end and is not shipped.

That Go is the go on PATH, or, with none, the Go release nomi was built with, which nomi downloads (The Go toolchain), so neither needs Go installed.

A WebAssembly target, js/wasm or wasip1/wasm, writes <name>.wasm by default. Nothing may follow a module’s last section, so the program goes inside the module:

  • A wasip1/wasm module carries it as one more active data segment, which the WebAssembly engine writes into a 4 MiB area of the nomi-vm’s own memory when it instantiates the module. The module reads its program from there, so it needs no file access: wasmtime run hello.wasm runs it, and so does a browser’s WASI shim with no file system.
  • The area is uninitialized memory, so it adds nothing to the file. It raises the module’s declared initial memory by 4 MiB, to 11.4 MiB for the reactor without the network and 14.9 MiB for the one with it. nomi build refuses a program whose compiled form is larger than the area, naming the limit.
  • A js/wasm module carries it in a custom section named nomi.image, which every runtime skips. A module cannot read its own sections, so it looks where its host can supply them. It uses globalThis.nomiImage when a loader has set it to the section’s bytes (new Uint8Array(WebAssembly.Module.customSections(module, "nomi.image")[0])), and otherwise reads the file argv[0] names through the host’s fs.
  • Go’s own loader runs a js/wasm module under Node unchanged: node "$(go env GOROOT)/lib/wasm/wasm_exec_node.js" hello.wasm. That loader hands the module Node’s whole environment as startup.env, and Go’s js/wasm runtime refuses to start when the arguments and environment together pass 8 KB (“total length of command line and environment variables exceeds limit”). In a large environment, run it with only what the program reads, as env -i PATH="$PATH" node .... nomi.js passes only the env its caller gives.

A wasip1/wasm program with at least one export fn is written as a WASI reactor instead of a command module (spec §7 Exported Functions). The program is appended to nomi-vm-reactor, the same VM linked as a reactor, which is found, built, downloaded and checked as nomi-vm is. nomi-wasi.js and nomi-wasi.d.ts, the JavaScript host for it, are written beside the module.

A project with Go bindings builds for a WebAssembly target as for any other: its nomi-vm, with the bound Go packages and the generated adapters linked in, is built for js/wasm or wasip1/wasm. Every bound package, and every package it imports, must build for that target. One that does not is an error at its gopkg, naming the target, the import chain to the package that does not build, and why: it has no Go files for the target, or Go’s first compile error there.

For example, modernc.org/libc has no files for either WebAssembly target, so a binding that reaches modernc.org/sqlite reads main.nomi:3:8: Go package "sq" does not build for js/wasm: it imports modernc.org/libc/sys/types (sq → modernc.org/sqlite → modernc.org/libc/sys/types), which has no Go files for js/wasm (build constraints exclude every one). A project with Go bindings and an export fn builds for wasip1/wasm as a reactor that links its bindings, with nomi-wasi.js and nomi-wasi.d.ts beside it.

The js/wasm build keeps the browser build’s limits: its file system is in memory, empty under Node, and a call nests at most 1,000 deep. A command-line program that reads real files belongs on wasip1/wasm. Every release ships a runner-only archive for each WebAssembly target, so a release nomi downloads it as it would any other platform’s. The js/wasm archive also carries the wasm_exec.js of the Go that built its nomi-vm, and the wasip1/wasm archive carries nomi-vm-reactor beside nomi-vm.

A program’s embed declarations (spec §18 Embedded files) are resolved when the program is compiled, so every build carries their files: an executable, a WebAssembly module, a --web folder’s app.wasm and a .nomic hold the bytes in the compiled program, and read no file but their own when they run. Delete the source tree and the build still serves its pages and applies its migrations. Patterns name files from the module root, as import paths do, whatever directory the declaring file is in.

A file’s contents are read when the program reads that file, never all at once. A built executable or .nomic keeps the files after its code and maps them, so starting it costs the same however much it embeds, and a file it serves is paged in by the operating system rather than held in the program’s memory; nomi build writes them from the files on disk without loading them whole. nomi run and nomi test read an embedded file from disk when the program reads it, and stop the program with an error naming the file if it changed after the program was compiled; run it again to embed the new contents. The REPL reads them from its working directory; a tour example reads its // FILE: data files.

A pattern whose folder or file does not exist yet, such as a frontend’s web/dist before its first npm run build, is a warning in nomi run, nomi check, nomi test, the REPL and the editor: the program compiles with that path as an empty directory, and a read under it returns NotFound. nomi build, for every target, refuses it as an error, so a release never carries an empty frontend. A program with such a warning is not kept in the artifact cache, so each run reports it, and the next run after the folder appears embeds its files.

Only the declarations a program reaches go into its build, so an embed nothing reads costs nothing, and a program with none is unchanged. The files count toward the compiled program’s size, so a wasip1/wasm module’s 4 MiB limit (above) includes them. nomi run --watch does not watch embedded files: a change to one is picked up at the next run.

A JavaScript frontend’s static build is embedded and served with http.file_server_embedded (Frontends). Each bundler needs three settings to match: the folder it writes, which the embed names and Files.sub makes the served root; a dev proxy that forwards /api to the Nomi server, so the page calls the API on its own origin; and the paths of the files whose names carry a hash of their contents, which immutable: lists.

BundlerOutput folderDev proxyimmutable:
Vitedist/server.proxy in vite.config.ts["assets/**"]
webpackdist/devServer.proxy["assets"], with output named assets/[name].[contenthash].js
Angulardist/<project>/browser/proxy.conf.json["*-*.js", "*-*.css"], the hashed files at its root
Create React Appbuild/"proxy" in package.json["static/**"]
SvelteKit, static adapterbuild/server.proxy, as Vite["_app/immutable/**"]
Next, output: 'export' in next.config.jsout/none["_next/static/**"]

http.file_server_embedded sends a .br or .gz copy that sits beside a file to a browser that accepts it. In Vite, a compression plugin (npm install -D vite-plugin-compression2) writes those copies. A React app’s web/vite.config.ts, with the proxy to a Nomi server on port 8080:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { compression } from "vite-plugin-compression2";

export default defineConfig({
  plugins: [react(), compression()],
  server: {
    proxy: { "/api": "http://localhost:8080" },
  },
});

A std host function that acts outside the program in a way some target cannot has a capability class: files for std::fs’s, processes for std::process’s, network for std::http’s requests, connect for std::net’s and std::tls’s dials and std::net’s lookups, and listen for a server or listener. Every target has files, a js/wasm module’s in memory. A js/wasm module sends HTTP requests through the browser’s fetch but cannot open other connections, start programs or serve; a wasip1/wasm module has none of the four.

nomi build walks what main, the boot and the exported functions can reach, and refuses a program that reaches a call of a class its target lacks. It writes nothing and lists each call in the program’s own code that reaches the class, at that call: the std function it calls (fs.read_text), the host function that one reaches (fs::host.read_text), and the functions the call is reached through. A hint follows, to build for another target or pass --allow-unsupported <class>.

The walk counts a call in a branch the program never takes, so --allow-unsupported <class> (repeatable) builds anyway. Such a call returns Err(io.Error.Unsupported{operation:, target:}) when it runs; it never traps. --no-vm names no target and is not checked.

A project with Go bindings is checked the same way, over the std calls it reaches. A Go binding itself carries no class: what a bound Go function does is opaque to the compiler, and whether its package builds for the target is for Go to decide (above). A bound function that reads a file in a js/wasm module reaches Go’s in-memory file system there, as std::fs’s calls do.

nomi build --web of a program that reaches files prints one line, nomi build --web: this program uses files; in the browser it sees only the files run's "files" option gives it.

nomi build <file> --no-vm [-o <out>] writes the compiled program alone (<name>.nomic in the working directory by default), for a nomi-vm that does not carry it, or for a reactor to load (Calling exported functions). It needs no Go toolchain and no nomi-vm, and the same file runs on every platform’s nomi-vm.

  • It records the program’s exported functions, so a program with an export fn and no fn main builds too. nomi-vm and nomi run refuse to run such a program, with this program has no `fn main`; it is called through its exported functions, and exit 1.
  • It refuses what nomi build refuses, with the same text.
  • It refuses a project with Go bindings, whose bindings only a VM built with them can run: nomi build --no-vm: this project has Go bindings, which only a VM built with them can run, so it has no portable compiled program.
  • --no-vm takes no --target and no --web. A test file has no compiled program.

A .nomic file is a header followed by the program’s image:

OffsetSizeField
08Magic: the bytes NOMIC and three zero bytes
84The program format version, a little-endian u32
124Flags, a little-endian u32. Bit 0: the program imports std::compiler. Every other bit is zero.
162n, the length of the next field, a little-endian u16
18nThe version of nomi that wrote it, in UTF-8, as nomi --version names it (the commit, or for a release, the tag and the commit)
18 + n8L, the image’s length, a little-endian u64
26 + nLThe image, the same bytes nomi build appends to nomi-vm

nomi build-vm [--target <goos>/<goarch>] [--compiler] [--no-network] [-o <out>] writes a copy of the nomi-vm that nomi build appends programs to, with no program: nomi-vm by default, with .exe or .wasm as the target needs. --no-network writes the smaller nomi-vm that nomi build uses for a program that never uses std::http, std::net or std::tls: it runs any other program, and refuses one that reaches the network before running it. It comes from where nomi build gets one, so a release needs no Go toolchain for it. For js/wasm it also writes the matching wasm_exec.js beside it. For wasip1/wasm it writes the command module.

nomi build-vm --reactor [--compiler] [--no-network] [-o <out>] writes nomi-vm-reactor with no program instead (nomi-vm-reactor.wasm by default), which takes its program through nomi_load (Calling exported functions). It writes nomi-wasi.js and nomi-wasi.d.ts beside it, the JavaScript host that runs it in a browser or Node, creating the folder they go in if it does not exist. The reactor exists only for wasip1/wasm, so that is its target, and --target with any other value is a usage error.

nomi build-vm takes no program file, and neither form takes nomi build’s --no-vm, --web or --static: a program with an export fn built with nomi build --target wasip1/wasm is already a reactor with that program inside it. --compiler writes the nomi-vm or reactor that links std::compiler’s hosts, which a compiled program importing std::compiler needs, and which needs Go to build.

A nomi-vm with no program of its own takes one when it starts:

nomi-vm <program.nomic> [args...]
nomi-vm [-] [args...]          # the .nomic file framed on stdin
nomi-vm --version
nomi-vm --help

Given a path, it reads the .nomic file there and passes the words after the path to the program as startup.args. Given no path, or -, it reads one .nomic file from the start of standard input, using the header’s length, and reads nothing past its last byte. The rest of standard input is the program’s own input, and the words after - are its arguments. So cat app.nomic input.txt | nomi-vm runs app over input.txt. Stdin is the way to hand a program to a host with no filesystem, such as a browser’s WASI shim.

  • A wasip1/wasm nomi-vm takes a path through a preopened directory (wasmtime run --dir=. nomi-vm.wasm app.nomic), and a js/wasm one under Go’s loader reads a path through Node’s fs (node wasm_exec_node.js nomi-vm.wasm app.nomic). Either takes the program on stdin.
  • A nomi-vm whose terminal is its standard input, or whose standard input is empty or not a .nomic file, prints its usage. A word starting with - other than these is a usage error.
  • A nomi-vm that nomi build appended a program to runs that program and treats every argument as the program’s, so ./app --version passes --version to app.

nomi-vm refuses a compiled program whose format version differs from the one it reads, before it runs anything: app.nomic was written by nomi v0.4.0 in program format 17, and this nomi-vm (nomi v0.5.0) reads format 18, followed by how to fix it. Programs written by different versions of nomi in the same format run. It also refuses a program with a flag it does not know, and a program importing std::compiler when it does not link that module’s hosts. A damaged or truncated file is an error naming it. All of these, and every usage error, exit 1, as a failed program does.

nomi run <file.nomic> [args...] runs a compiled program in the nomi process, as nomi-vm would, with std::compiler’s hosts linked. nomi run recognizes a .nomic file by its first eight bytes, whatever its name.

nomi build <file> --web [-o <dir>] [--static <dir>] writes a folder that any static file host can serve, which runs the program’s main in a browser. The default folder is <name>-web in the working directory. It holds the generated files and the author’s static files:

FileWhat it is
app.wasmThe js/wasm module --target js/wasm writes, with its memory capped at 1 GiB.
nomi.jsAn ES module: the loader and its run function, with Go’s JS support file wasm_exec.js from the Go toolchain that built the js/wasm nomi-vm inside it. Each run starts this same file as its module worker.
index.htmlA page that runs main with an output pane and an input line.
locales/<tag>.nomilFor a program that lists its locales, one file per listed locale [i18n].web_embedded leaves out: its CLDR data and translations, which the program loads with Locale.load (Locales in the browser).

nomi.js runs wasm_exec.js only where a program runs: in the worker, or on the page for a worker: false run. A page whose programs run in workers gets none of the globals wasm_exec.js sets (Go, and fs, process and path when missing). Since the worker is a file the host serves and not a blob: URL, a policy of worker-src 'self' allows it.

The static files are the files of a web/ folder: the one at the root of the program’s project, beside its nomi.toml, or, for a file outside a project, the one beside the file. --static <dir> names another folder in its place; it must exist, while a missing web/ folder only means there are no static files.

  • Every file under the folder is copied to the same path in the output, subfolders included (web/img/logo.png becomes img/logo.png), except files and folders whose names start with a dot.
  • A static file wins over a generated one of the same name, so web/index.html replaces the generated page; such a page loads nomi.js and calls run itself.
  • A static app.wasm or nomi.js is refused, naming the file: nomi build --web: web/app.wasm: the build writes app.wasm, so a static file cannot have that name. So is a static file in locales/ ending in .nomil, which the build writes, and an output folder inside the static folder.
  • A rebuild replaces only the generated files and the static files it copies. Anything else in the output folder stays, such as a host’s _headers, and so does a file copied by an earlier build whose source has since been deleted from web/.
  • A rebuild removes each locale file an earlier build wrote that it does not write. It also removes a wasm_exec.js, nomi-web.js or nomi-worker.js whose contents are exactly what an older nomi build --web wrote there, and leaves a file of that name with any other contents. A static file may have one of those names, and is copied like any other.

--static without --web is a usage error, and so is --web with a --target other than js/wasm. A project with Go bindings builds: app.wasm is its own nomi-vm, with the bound Go packages linked in, built for js/wasm as --target js/wasm builds it (Executables), and a bound package that does not build for js/wasm is an error at its gopkg. A program importing std::compiler builds, and its app.wasm is larger because its nomi-vm links the front end; nomi build says how to serve a module over 20 MB.

A page runs the program with run:

import { run } from "./nomi.js";

const { exitCode, fatal } = await run("./app.wasm", {
  args: ["--verbose"],     // startup.args; default []
  env: { NAME: "x" },      // startup.env; default {}
  stdout: (text) => {},    // default: console.log, one call per line
  stderr: (text) => {},    // default: console.error, one call per line
  stdin: "all of it\n",    // or an async () => string | null; default: end of input
  timeoutMs: 10_000,       // default: none
  signal: controller.signal,
  locales: "./locales/",   // where Locale.load fetches <tag>.nomil; default beside app.wasm
  files: { "data/prices.csv": csvText },  // the program's files, string or Uint8Array; default none
  setup: "./setup.mjs",    // a module whose default export runs, awaited, before the program; default none
});
// files: every file in the program's file system when it ended, by path, as Uint8Array

run fetches and compiles the module once per URL; every later run of it reuses the compiled module. Each run gets a fresh instance in its own worker, so a page stays responsive while a program loops, and timeoutMs and signal can stop it. The run then resolves with exit code 124 (timeout) or 130 (abort) and a fatal text. worker: false runs on the page’s own thread, one run at a time; a timeout or abort then resolves the run and drops its output, but cannot stop the program.

  • Output reaches the callbacks as written, so a prompt written with io.write and no newline appears before the program waits for input.
  • Standard input is a string, served and then ended; an async function, asked for one line at a time, with null ending the input; or absent, so io.read_line returns Ok(None) at once.
  • The environment holds what env gives plus NOMI_COLOR=never, unless env sets it, so diagnostics carry no colour codes. Nothing comes from the page’s URL or cookies. Arguments and environment together must fit in the 8 KB Go’s loader reserves for them.

setup (of run and load) is a module URL, resolved as url is, for what a program’s Go bindings need from JavaScript before it starts. The module is imported where the program runs, in its worker or on the page for worker: false, and its default export is called and awaited before the program’s first instruction. A setup that throws or rejects ends the run with exit code 2 and a fatal naming the module. The sqlite driver’s browser build is one user: it calls SQLite’s WebAssembly build through globalThis.sqlite3, which its setup module sets with globalThis.sqlite3 = await sqlite3InitModule().

The exit code is nomi run’s: 0, an Exit’s code (spec §15 Entry callbacks), or 1 for a main returning any other Err, a trap or a failed assertion. When the Go runtime stops (an allocation past the 1 GiB cap, a deadlock), the run resolves with exit code 2 and Go’s own line, such as fatal error: out of memory, as fatal.

The browser build’s limits apply as under --target js/wasm: the program’s file system is in memory (std::fs), a call nests at most 1,000 deep, and no signal arrives. The file system starts with the files files gives, by path from its working directory /work. The run resolves with files, every file in it when the program ended, by the same paths (absolute for a file outside /work); a run stopped by timeoutMs or signal has no files. The clock, std::random, tasks, channels and sleep work. Tasks share the worker’s one thread, so a task that never yields starves the others.

index.html loads nomi.js with a <script type="module" src> and no inline script, so it works under a strict script-src. nomi.js mounts itself on every element with a data-nomi-program="app.wasm" attribute: an output pane with standard error in a distinct colour, an input line that is enabled while the program waits for a line (Enter sends it, Ctrl-D on an empty line ends the input), the exit status, and a button that runs the program again. A page that imports run itself needs no such element.

The page needs a server, since a browser does not fetch modules from file: URLs: python3 -m http.server -d hello-web serves one locally. Serve app.wasm as Content-Type: application/wasm, compressed with brotli or gzip (a hello world is 11 MB, 2 MB with brotli); Cloudflare Pages, Netlify and Vercel do both themselves. Without that content type the loader still works, compiling from the whole response instead of streaming it.

nomi run --web [--port N] [--open] [--static <dir>] <file> is the loop for working on such a program:

  • It builds the generated files into a temporary directory and serves them, with the static files served from where they are, by the same rule and with the same precedence and refusals as nomi build --web.
  • It serves on http://localhost:<port>/, on port 8000 or the next free one up to 8099 unless --port names one (--port 0 takes any free port), with app.wasm as application/wasm, the locale files as application/json, and every response marked Cache-Control: no-cache. It prints the URL; --open also opens it in the default browser.
  • It watches the entry, every file the program loads, the project’s nomi.toml, and the go.mod and Go files beside the program’s files, polling them every 250 ms, and rebuilds once a burst of changes has settled. The page reloads itself after a successful rebuild. It polls the static folder too, and a change there reloads the page without a rebuild.
  • A failed build is printed on the terminal and shown over the page, which keeps running the last build that succeeded until the error is fixed; when the first build fails, the page shows the error alone. A static file given a generated name while the server runs is reported the same way and not served.
  • Every .html page served, the generated one or a static one, gets one more script, /__nomi/dev.js, added before its </head> (or at its end when it has none). It listens to the server-sent event stream /__nomi/events. Each event is {"build": n, "static": m, "error": "..."}: n counts the successful builds and m the changes to the static files, and a page reloads when either differs from the one it was served at. nomi build --web never writes any of this.
  • Ctrl-C stops the server and removes the temporary directory. A project with Go bindings is served as --web builds it.

The browser program takes no arguments, so a word after the file is a usage error. --port, --open and --static without --web are usage errors too, and so is --watch with --web, since --web already rebuilds on every change. Without --web, nomi run takes only --watch (--watch), --profile (--profile) and --offline before the file, and every word after the file is the program’s.

A program with exported functions (spec §7 Exported Functions) needs no fn main. nomi check and nomi test treat it as any program. Exported functions are lowered whether or not main reaches them, so nomi check reports an exported body the VM cannot run as it reports one main reaches. nomi run of such a program with no main is the error <file> declares no `fn main`, so there is no program to run; its exported functions are called by a host, so build it for a page with `nomi build --web`, or as a WASI reactor with `nomi build --target wasip1/wasm`, and a plain nomi build gives the same error for build. nomi build --web and nomi build --target wasip1/wasm build it.

Calling from a page. nomi build --web records each exported function in the program it builds, and nomi.js beside it loads the program once and calls the functions any number of times:

import { load } from "./nomi.js";

const nomi = await load("./app.wasm");
let game = await nomi.call("new_game", "pipeline");
game = await nomi.call("guess", game, "e");

load(url, options) starts the program in its own worker and runs its main first when it has one, so main can print or force once values; its output goes to options.stdout and options.stderr as run()’s does. It resolves when the functions can be called, and rejects with main’s failure when main fails. call(name, ...args) encodes the arguments as JSON, runs the function, and resolves with its decoded result. Calls run one at a time, in the order they are made, on the one program, so a once value an earlier call forced is not computed again. A call that traps, or whose argument its parameter’s FromJson refuses, rejects with an Error whose message is the Nomi diagnostic (argument `game` of `guess(game: Game, letter: String): Game`: guesses: expected List<String>, got missing), and the next call runs normally; so does a call to a name the program does not export, whose error lists the exported names. exports() resolves with each exported function’s name, parameters, result type and signature, and close() stops the worker.

nomi build --web also writes nomi.d.ts, TypeScript declarations for nomi.js with a typed call overload for each exported function, and a declaration for each type the functions name. A type maps as nomi types maps it, except an Int, which is number | bigint, since nomi.js hands JavaScript an Int past Number.MAX_SAFE_INTEGER as a BigInt.

Calling from a WASI host. nomi build --target wasip1/wasm writes one of two module shapes, chosen by the program, with no flag. Either carries its program in its own linear memory, so it needs no file access, no environment and no particular argv: a browser’s WASI shim with no file system, or any runner that only calls its exports, runs it.

  • No export fn: a command module. It exports _start, which runs main with WASI stdin, stdout and arguments, then exits.

  • At least one export fn: a reactor. It exports _initialize, which the runner calls once (the WASI reactor convention), its memory, and a generic call ABI over that memory:

    ExportSignatureDoes
    nomi_alloc(len: i32) -> i32reserves len bytes and returns a pointer the runner writes into
    nomi_call(name_ptr, name_len, args_ptr, args_len: i32) -> i64calls the exported function named by the UTF-8 name with the JSON array of arguments; returns the result’s pointer in the high 32 bits and its length in the low 32 bits
    nomi_free(ptr, len: i32)releases a buffer from nomi_alloc or a result from nomi_call or nomi_load
    nomi_main() -> i32runs main over WASI stdin, stdout and stderr and returns the exit status nomi run would exit with
    nomi_load(ptr, len: i32) -> i64boots the compiled program (.nomic) at ptr in a reactor that has none, or with len 0 the program built into the module; returns its result as nomi_call does

The result is UTF-8 JSON: {"ok": value} on success, with null for a Unit result, and {"error": "diagnostic"} on a trap, a FromJson failure or an argument list that is not a JSON array of the right length. The module stays usable after an error. A name the program does not export is an error result naming the exported functions. nomi_call copies the name and the arguments before it runs anything, so the runner may free them as soon as it returns; a result stays where it is until nomi_free releases it.

A runner in JavaScript, after instantiating the module with its WASI imports:

wasi.initialize(instance);
const x = instance.exports;
const put = (text) => {
  const bytes = new TextEncoder().encode(text);
  const ptr = x.nomi_alloc(bytes.length);
  new Uint8Array(x.memory.buffer, ptr, bytes.length).set(bytes);
  return [ptr, bytes.length];
};
const [name, nameLen] = put("guess");
const [args, argsLen] = put(JSON.stringify([game, "e"]));
const packed = BigInt.asUintN(64, x.nomi_call(name, nameLen, args, argsLen));
x.nomi_free(name, nameLen);
x.nomi_free(args, argsLen);
const ptr = Number(packed >> 32n), len = Number(packed & 0xffffffffn);
const answer = JSON.parse(new TextDecoder().decode(new Uint8Array(x.memory.buffer, ptr, len)));
x.nomi_free(ptr, len);

The program boots on the first nomi_call or nomi_main, and every later call runs on that booted program, so a once value an earlier call forced is not computed again. A boot that fails makes every nomi_call return its error. main does not run unless the runner calls nomi_main, which it may do before, between or after calls; in a program with no fn main it writes this program has no `fn main`; it is called through its exported functions to stderr and returns 1. Calls run one at a time: the module is single-threaded, and tasks a call starts make progress only while some export is running.

Loading a program into a reactor. A runner that runs many scripts can ship the reactor once and each script as a small .nomic file (Compiled programs and nomi-vm). nomi build-vm --reactor writes the reactor with no program of its own: the module a program with an export fn is embedded in, with its image area empty. The runner compiles it once, instantiates it for each script, calls _initialize, writes the whole .nomic file, header included, into a buffer from nomi_alloc, and calls nomi_load with it. nomi_load copies the bytes before it returns, boots the program, and returns like nomi_call:

  • {"ok": ["add(a: Int, b: Int) -> Int", ...]} on success: the program’s exported functions as export fn declares them, without export fn, in declaration order. A program with only a main returns {"ok": []}.
  • {"error": "..."} when the bytes are not a .nomic file (the loaded program: not a compiled Nomi program (.nomic)), are cut short or carry bytes after the program, are in a program format this reactor does not read (the text nomi-vm gives, above), import std::compiler in a reactor that does not link its hosts, hold neither a fn main nor an export fn, or the program’s boot fails.

After a successful load, nomi_call and nomi_main work on the loaded program exactly as on an embedded one. A failed load leaves the reactor with no program, so the runner may load again. A reactor with no program returns nomi_call with {"error": "this reactor has no program yet: write a compiled program (.nomic) into memory from nomi_alloc and pass it to nomi_load first"}, and nomi_main writes that text to stderr and returns 1.

One instance runs one program. A second nomi_load after a successful one is an error result, this reactor already loaded a program, and a reactor runs one program for its life. To run another, instantiate the module again, and the loaded program keeps running. A booted program leaves state behind in the instance (its once values, the tasks it started, the memory it grew), and nothing can return an instance to the state _initialize left it in; instantiating the compiled module again gives a clean one cheaply, since the engine compiles a module once however many instances it makes. A reactor nomi build embedded a program in refuses nomi_load the same way: this reactor carries the program `nomi build` embedded in it, so it loads no other. Load programs into a reactor `nomi build-vm --reactor` writes, which carries none.

nomi_load with a length of 0 loads nothing (ptr is not read). In a reactor nomi build embedded a program in, it boots that program, as the first nomi_call would, and returns as a load does: the exported functions’ signatures, or the boot’s error. A runner calls it to learn what it can call before it calls anything; calling it again returns the same. In a reactor with no program it is the error result this reactor has no program built in: pass it a compiled program (.nomic), and the reactor stays ready for a load.

nomi build-vm --reactor also writes nomi-wasi.js beside the reactor, with its TypeScript declarations in nomi-wasi.d.ts, and nomi build --target wasip1/wasm writes both beside a reactor it embeds a program in: the toolchain’s JavaScript host for this ABI, an ES module that runs in browsers and in Node with no WASI library, as Go’s wasm_exec.js is the host for js/wasm. It implements the WASI preview1 imports the reactor needs (no preopened directories; an import it does not know returns ENOSYS), and over the ABI above it offers loadRuntime(reactor), which compiles the module once; runtime.load(nomic), which instantiates it, calls nomi_load, and resolves to a program whose exports are the load’s signatures and whose call(name, ...args) JSON-encodes the arguments, calls nomi_call, and resolves with ok or rejects with an Error carrying error; and runtime.run(nomic, {stdin:, args:, env:}), which loads into a fresh instance, calls nomi_main, and resolves with its exit status and output. Without nomic, load() and run() call nomi_load with length 0, so they use the program built into the module, and reject with that error result on a reactor that has none; a .nomic handed to a reactor with a program built in rejects with the refusal above. A WASI call is synchronous, so a sleeping task blocks the calling thread for its duration (with Atomics.wait where the thread may block, by spinning elsewhere).

The reactor’s exports are the same for every program: a program’s own function names travel as data, in nomi_call’s name, rather than as per-function exports such as guess(i32, i32) -> i32. A project with Go bindings and an export fn gets a reactor of its own, with the bound Go packages linked in, which exports the same functions.

A program carries the CLDR data of the locales its nomi.toml lists under [i18n].locales ([i18n]), and nothing else. A program with no [i18n] table, a script outside any project among them, carries every locale CLDR has data for. A locale the program does not list still formats, as its nearest listed parent or else as the source locale, so it is not an error at run time; a Locale"…" literal of one is a compile error. Locale.available has the lookup rules. The grammatical genders and cases of each carried locale’s nouns, which a noun’s catalog entries may give (spec §18 Nouns and agreement), are carried data too.

nomi run, nomi test, the REPL and a built program (Executables) read the same data, so a program prints the same text under each. A built program carries the data in its image, cut to the parts it reaches: one that formats numbers and never lists items carries no list patterns, and one that reads no locale data carries none. The collation data (std::collation) is the root order, which a program that compares with a Collator carries once, and each carried locale’s tailoring. The Chinese and Korean tailorings are carried only by a program that lists a locale whose collation chain reaches them; one that lists no locales sorts Chinese and Korean in the root order.

std::calendar embeds Go’s time/tzdata package (≈ 450 KB) so IANA zone lookups (America/New_York, Asia/Tokyo, …) work on every host without requiring system-provided tzdata.

A site may offer many locales while each reader reads one, so nomi build --web does not put them all in app.wasm. It compiles in the locales [i18n].web_embedded names (the source locale unless it says otherwise), with CLDR’s root, every listed locale’s plural rules and grammatical features, and every phrase’s source text, and writes each other listed locale to locales/<tag>.nomil beside it: that locale’s numbers and lists and its phrases’ and nouns’ translations, with those of each ancestor on its fallback chain that is not embedded either, so one file serves the locale (pt-PT’s holds pt’s too). Every locale is still checked when the program is built. A program that lists no locales, a program with no phrases that formats nothing, and every other kind of build carry every locale in the program.

A program shows a page in a locale only after Locale.load has fetched its file, which the calling task waits for. A file another build wrote, such as one a browser cached from the last deploy, is refused: the image and its files share a build id. Anywhere but a browser build Locale.load returns at once.