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.
Add, update and remove dependencies
Section titled “Add, update and remove dependencies”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 ingo.mod(its latest release when no version is given, else a full version such asv1.2.3), with at least the versions of what it requires, download it, and write the checksums togo.sum. A Go package’s path adds the module that holds it, the longest prefix of the path the proxy has. A releasenomiadds a first-partylib/module with no version at the commit it was cut at, whose Go side it carries prebuilt (Go bindings);@latesttakes 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 itsgo.mod) andreplaceit with the directory, relative to the project root. A directory without ago.modor anomi.tomlis refused.nomi remove <module>: take a requirement, and anyreplaceof it, out ofgo.mod, with each// indirectrequirement no remaining module’sgo.modrequires, and their lines out ofgo.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 withgopkg, 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, asgo get -udoes: never a new major version (that is another path,/v2), and never a pre-release. It raises what the new versions require, writesgo.sum(dropping the old versions’ zip checksums), and prints each change as<path> <old> -> <new>. Alib/module has no releases: its latest is the latest commit, except on a releasenomi, which moves everylib/module to the commit it was cut at.nomi fetch [--target <goos>/<goarch>]... [dir]: download everything the project needs: the modules (adding togo.modwhat a Nomi dependency requires), and, for a project with Go bindings, the Go toolchain when there is nogo, the Go modules its bindings link, and the runner for each--target. A later command with--offlinethen needs no network.--offlineonrun,test,check,build,fetchandadd: download nothing; a module or toolchain the caches lack is an error that names it.GOPROXY=offrefuses module downloads the same way.
Dependencies
Section titled “Dependencies”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.modrequires directly (no// indirect), and, for each that is a Nomi module, the modules that module’sgo.modrequires and the project’sgo.modalso lists. Each is taken at the version the project’sgo.modrequires;nomi add,nomi updateandnomi fetchkeep that list complete, asgo mod tidydoes, andnomi removedrops what no module needs any more.run,test,checkandbuilddownload them for a Nomi module (anomi.tomlbeside itsgo.mod); a Go module that merely holds.nomifiles leaves its Go dependencies to thegocommand. - Download. Module zips come from
GOPROXY(defaulthttps://proxy.golang.org,direct) through the module proxy protocol, into the Go module cache (GOMODCACHE), which thegocommand shares; a module already there is not downloaded again. A module thatGOPROXY,GONOPROXYorGOPRIVATEsendsdirectis read from its version control repository by thegocommand. - Verification. Each zip’s hash is checked against
go.sum. A modulego.sumdoes not list is checked against the checksum database (GOSUMDB, defaultsum.golang.org;GONOSUMDB,GOPRIVATEandGOSUMDB=offexempt modules as they do for Go). A hash that differs from either is an error and installs nothing. - When
go.sumchanges.nomi add,nomi updateandnomi fetchwrite the checksums of what they download togo.sum, andnomi removeandnomi updatedrop the lines of what they took out.nomi run,test,checkandbuilddownload what is missing but, as Go’s-mod=readonlydefault, refuse a modulego.sumdoes not list and say to runnomi fetch;GOFLAGS=-mod=modlets 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
Section titled “Distribution”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.
No lock file
Section titled “No lock file”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.