Skip to content

Go bindings

A program with gopkg bindings needs a Go toolchain, unless every binding is a first-party lib/ module’s (the SQLite and Postgres drivers, sqlkit, markdown, image, the password hashers) and the nomi is a release. Pure-Nomi programs and tests need none.

  • A release carries the lib/ modules’ Go side prebuilt, at the commit it was cut at: nomi-lib, which nomi run, nomi test and nomi check run such a program in, and nomi-vm-lib, which nomi build appends it to, for each native platform and js/wasm. They ship in a lib archive per platform beside the main one, which nomi downloads from its release the first time it needs it unless it is unpacked beside nomi, and they must come from the same commit as nomi. nomi add takes a lib/ module at that commit, and nomi update moves every lib/ module to it. A project that also has a binding of its own, or a lib/ module at another commit, builds a wrapper with Go as below; with no Go, the error names the binding or the version, and for a version, that nomi update aligns it. wasip1/wasm has no prebuilt lib/ runner, since modernc.org/sqlite does not build for it.
  • nomi run, nomi check and nomi test compile the bound packages, with Nomi’s own Go module, into a wrapper they cache under the user cache directory (nomi/builds/, safe to delete). The first run of a project is slower; later runs reuse the wrapper until the project’s Go code, its go.mod or nomi changes, and editing .nomi files never rebuilds it. A released or go installed nomi compiles against Nomi’s module at its own version, which Go fetches; one built from a clone compiles against the clone (Installing Nomi).
  • With no go on PATH, nomi downloads the Go release it was built with and uses that (The Go toolchain).
  • A bound package may be in a module from the Go module cache, a dependency’s included.
  • Go bindings build with CGO_ENABLED=0, so a gopkg naming a package that needs cgo, itself or through a package it imports, is a check error at the path: gopkg "example.com/app/wrap": needs cgo: it imports example.com/cdriver/internal/csql (...), whose files import "C", and Go bindings build with CGO_ENABLED=0.

A module’s Go code (the gopkg bindings of spec §19), in the project or in a dependency, is built into the program’s runner with a Go toolchain: the go on PATH; or, with none, the Go release nomi was built with, which nomi downloads once from go.dev, checks against a SHA-256 compiled into nomi, and keeps in its cache (<user cache>/nomi/go/). NOMI_GO names a go (or a Go root) to use instead of both. The language server uses that toolchain only once it is downloaded.