Skip to content

Modules and dependencies

A Nomi module’s identity is split between go.mod (Go-side identity and dependencies) and nomi.toml (Nomi-side identity and entry points). A Nomi module is a Go module, so it is published by pushing a version tag and fetched through the Go module proxy, without the go command. nomi publish is a reserved name with no command behind it, there is no Nomi-specific registry (Distribution), and the compiler does not check semantic versions.

Run these in the project’s directory. They write go.mod and go.sum, which the project commits; nobody edits go.mod by hand.

  • nomi add <module>[@version]: require a module in go.mod (its latest release when no version is given, else a full version such as v1.2.3), with at least the versions of what it requires, download it, and write the checksums to go.sum. A Go package’s path adds the module that holds it, the longest prefix of the path the proxy has. A release nomi adds a first-party lib/ module with no version at the commit it was cut at, whose Go side it carries prebuilt (Go bindings); @latest takes the latest commit.
  • nomi add <directory>, for an argument that starts with ./, ../ or /: require the Nomi module in that directory (require <its module path> v0.0.0, from its go.mod) and replace it with the directory, relative to the project root. A directory without a go.mod or a nomi.toml is refused.
  • nomi remove <module>: take a requirement, and any replace of it, out of go.mod, with each // indirect requirement no remaining module’s go.mod requires, and their lines out of go.sum. <module> is the module path or the module’s short name. It refuses while a Nomi file of the project imports the module, or binds a Go package of it with gopkg, and names the file and line.
  • nomi update [module]: move one requirement, or every one not replaced with a directory, to the highest release of its module path, as go get -u does: never a new major version (that is another path, /v2), and never a pre-release. It raises what the new versions require, writes go.sum (dropping the old versions’ zip checksums), and prints each change as <path> <old> -> <new>. A lib/ module has no releases: its latest is the latest commit, except on a release nomi, which moves every lib/ module to the commit it was cut at.
  • nomi fetch [--target <goos>/<goarch>]... [dir]: download everything the project needs: the modules (adding to go.mod what a Nomi dependency requires), and, for a project with Go bindings, the Go toolchain when there is no go, the Go modules its bindings link, and the runner for each --target. A later command with --offline then needs no network.
  • --offline on run, test, check, build, fetch and add: download nothing; a module or toolchain the caches lack is an error that names it. GOPROXY=off refuses module downloads the same way.

A required module comes from the Go module proxy, as the go command fetches it, with no Go toolchain needed for a module that is all Nomi:

  • Which modules. A project needs the modules its go.mod requires directly (no // indirect), and, for each that is a Nomi module, the modules that module’s go.mod requires and the project’s go.mod also lists. Each is taken at the version the project’s go.mod requires; nomi add, nomi update and nomi fetch keep that list complete, as go mod tidy does, and nomi remove drops what no module needs any more. run, test, check and build download them for a Nomi module (a nomi.toml beside its go.mod); a Go module that merely holds .nomi files leaves its Go dependencies to the go command.
  • Download. Module zips come from GOPROXY (default https://proxy.golang.org,direct) through the module proxy protocol, into the Go module cache (GOMODCACHE), which the go command shares; a module already there is not downloaded again. A module that GOPROXY, GONOPROXY or GOPRIVATE sends direct is read from its version control repository by the go command.
  • Verification. Each zip’s hash is checked against go.sum. A module go.sum does not list is checked against the checksum database (GOSUMDB, default sum.golang.org; GONOSUMDB, GOPRIVATE and GOSUMDB=off exempt modules as they do for Go). A hash that differs from either is an error and installs nothing.
  • When go.sum changes. nomi add, nomi update and nomi fetch write the checksums of what they download to go.sum, and nomi remove and nomi update drop the lines of what they took out. nomi run, test, check and build download what is missing but, as Go’s -mod=readonly default, refuse a module go.sum does not list and say to run nomi fetch; GOFLAGS=-mod=mod lets them write it.
  • The language server reads only the module cache and never downloads. An import of a module that is required and not in the cache is an error whose hint says to run nomi fetch.

Distribution rides on the Go module proxy: a Nomi module is a Go module, so a module pushed with a version tag to a public repository (GitHub, GitLab, etc.) is served by proxy.golang.org and fetched as Dependencies above describes. Several modules may share one repository, each in a subdirectory with its own go.mod and tags prefixed by it (sqlite/v0.3.0), as Go lays them out.

There is no Nomi-specific registry, and none is planned.

Nomi has no lock file of its own. A Nomi module’s dependencies are Go module requirements, so go.mod pins their versions and go.sum their contents, and nomi checks every download against it (Dependencies above); a separate nomi.lock is not planned.