Building & Shipping
nomi run runs a program while you work on it. When you want to give the
program to someone else, nomi build packages it. This chapter covers each
way to package it, starting with the most common. The tooling reference’s
Building page lists every flag and every file each
build writes.
Executables
Section titled “Executables”$ nomi build app.nomi # writes ./app $ nomi build app.nomi --target linux/amd64 # for another platform
nomi build writes one executable file. It needs nothing else installed to
run, because it holds both your program and the Nomi VM
that runs it. --target builds for another platform, the way Go does.
Executables lists what nomi build
refuses and where it finds the VM for each target.
You can also build the program without the VM:
$ nomi build --no-vm app.nomi # writes app.nomic
app.nomic is small, about 1 KB for hello world, because it holds only the
code your program uses. To run it, you need the VM: nomi-vm app.nomic, or
nomi run app.nomic. nomi build-vm writes nomi-vm for you.
A program that reads files it ships with, such as pages, templates or
migrations, can carry them inside itself. An embed declaration names
them by pattern, from the module root as imports are, and the build carries
them, so the executable needs no other file. It reads a file’s bytes from
itself when the program reads that file, so a large embed costs nothing at
startup:
// FILE: main.nomi
import
std::embed.Files
std::io
end
embed site `static`
fn main()
io.print(Files.paths(site))
io.print(Files.read_text(site, "static/index.html")!)
end
// FILE: static/index.html
<h1>Hello</h1>
// FILE: static/style.css
h1 { color: teal }[static/index.html, static/style.css]
<h1>Hello</h1>
Embedded files
has the pattern rules, and std::embed the Files API.
A .nomi file can also run as a script. Make its first line
#!/usr/bin/env nomi and make the file executable. Then ./hi.nomi a b
runs it, the same as nomi run hi.nomi a b. Scripts
says how a script finds the files it imports.
Web pages
Section titled “Web pages”$ nomi build app.nomi --web # writes a folder
This writes a folder you can put on any static web host. Opening its page runs your program in the browser, the way the examples on this site run. The folder holds:
app.wasm: your program and the VM, as WebAssemblynomi.js: the JavaScript that runs itnomi.d.ts: TypeScript types fornomi.jsindex.html: the page
While you work, nomi run --web app.nomi serves the page at
http://localhost:8000/, or the next free port (--port picks one). Each
time you save, it rebuilds and reloads the page. If the build fails, the
error shows on the page until you fix it. --open opens the page in your
browser.
To use your own page, scripts or images, put them in a folder named web/
at your project’s root, beside nomi.toml, or beside the program when it is
in no project. Both commands include it, and a web/index.html
replaces the generated page. Your page runs the program with run from
nomi.js.
A page has no disk, so a program’s files are in memory. The page hands
them to run, by path, as text or bytes, and run returns every file the
program left when it ends:
import { run } from "./nomi.js"; const { exitCode, files } = await run("./app.wasm", { files: { "data/prices.csv": csvText }, }); const report = new TextDecoder().decode(files["report.txt"]);
nomi build --web notes when a program uses files, since in the browser it
sees only the ones files gives it. A program built with --target js/wasm and run under Node starts with no files, and a command-line
program that reads real files belongs on --target wasip1/wasm, which has
the directories its runner opens for it. Every option run takes, and what
the folder holds, is in A program in the browser.
A program with Go bindings builds for the browser too.
nomi build --web compiles your Go code, and the Go packages it uses, into
app.wasm, as nomi build compiles them into an executable. Every one of
those packages must build for WebAssembly. Most pure Go does. A package
that only works on some operating systems is an error at its gopkg,
which names the package that stops the build. modernc.org/sqlite is one,
because modernc.org/libc, which it uses, has no WebAssembly version.
The same goes for --target js/wasm and --target wasip1/wasm.
Calling Nomi from a page
Section titled “Calling Nomi from a page”A page can also call functions in your program, as often as it likes. Mark
each function the page may call with export:
import std::json.{FromJson, ToJson}
struct Game
word: String
guesses: List<String>
end
derive ToJson for Game
derive FromJson for Game
export fn new_game(word: String) -> Game
Game{word:, guesses: []}
end
export fn guess(game: Game, letter: String) -> Game
{..game, guesses: [letter, ..]}
end
Values go between JavaScript and Nomi as JSON, so each type they use derives
ToJson and FromJson. A program like this needs no main.
Build it with nomi build game.nomi --web, or serve it with
nomi run --web game.nomi. Then your page loads it and calls its functions.
A Nomi struct arrives as a plain JavaScript object, and you pass it back the
same way:
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"); // { word: "pipeline", guesses: ["e"] }
If a call fails, its promise rejects with the Nomi error, and the next call
still works. The folder’s nomi.d.ts lets your editor check each call
against the Nomi function.
Renaming an exported function, or changing its parameters, breaks the page, and the compiler can’t tell you. To keep that risk in one place, put the exported functions in a small file of their own that calls your other code.
WebAssembly runners
Section titled “WebAssembly runners”A --web page suits one program that drives the page. For other
WebAssembly hosts, build for wasip1/wasm:
nomi build-vm --reactorwrites a VM,nomi-vm-reactor.wasm, withnomi-wasi.jsbeside it. A page or a Node program loads the VM once and then loads many small scripts into it, each one written bynomi build --no-vmas a.nomicfile, and calls their exported functions or runs theirmain.nomi build --target wasip1/wasm app.nomiwrites one module with the VM inside.nomi-wasi.jscan load it, and a WASI runner such as wasmtime runs itsmainlike any command-line program.
Calling exported functions
covers nomi-wasi.js’s API and the functions a module provides to a host of
your own.
That ends the language tour. The Libraries chapters, starting with Dates & Times, show programs built on the standard library, and the Standard Library reference covers every module.