.GO File Format – Packages and modules

Package initialisation

Within a package, package-level variables are initialised stepwise. Each step takes the variable that is earliest in declaration order and has no dependencies on uninitialised variables. Variables left over at the end form initialisation cycles, and the program is invalid (spec: Package initialization).

• Several variables initialised by one multi-valued expression are initialised together.
• Blank variables are treated like any others.
• The order across files is the order the files are presented to the compiler. Build systems are encouraged to use lexical file name order; the go command does.
• Dependencies are found by lexical references to variables, functions and non-interface methods, analysed transitively within the package. Hidden dependencies, such as through an interface method call, are not seen.

var (
	a = c + b  // == 9
	b = f()    // == 4
	c = f()    // == 5
	d = 3      // == 5 after initialisation has finished
)

func f() int {
	d++
	return d
}

// The initialisation order is d, b, c, a.

Then all init functions in the package run, in the order they appear in the source, across files in the order given to the compiler. A package may have any number of init functions, even several in one file. Each takes no arguments and returns nothing, and none can be referred to from code.

Program initialisation

Packages are initialised one at a time, each only once, and imports before importers. Since Go 1.21 the order is exact: given all packages sorted by import path, each step initialises the first uninitialised package in the list whose imports are all initialised (spec: Program initialization). Initialisation runs in a single goroutine, sequentially, although an init function may start other goroutines.

Module paths and major versions

A module path names the module and is the prefix of its packages’ import paths. A path must not begin or end with a slash, and its elements use ASCII letters, digits and -, ., _ and ~. A path element may not begin or end with a dot.

• Versions follow semantic versioning, written with a v: v1.2.3.
• A module released at major version 2 or higher must end its path with a suffix such as /v2. The suffix is not allowed at v0 or v1.
• Paths beginning with gopkg.in/ always carry a suffix with a dot, as in gopkg.in/yaml.v2.

The go directive

The go directive says which semantics a module was written for. The compiler rejects language features newer than that version, in packages of the module, and a file may also set its own version with a build constraint. If the directive is missing, go 1.16 is assumed.

• Since Go 1.21 the go line is a strict minimum: toolchains refuse to use a module that declares a newer Go version. The go command can find or download a suitable toolchain automatically.
• At go 1.21 or later, a module’s go line must be at least that of all its dependencies.
• At go 1.17 or later, a go.mod file lists every module that provides a transitively imported package, which lets the module graph be pruned.
• The go line also selects the defaults for behaviour controlled by GODEBUG.

go.sum

A go.sum file beside go.mod holds cryptographic hashes of the module’s direct and indirect dependencies. Each line has a module path, a version (ending in /go.mod when the hash covers only the go.mod file) and a hash, such as h1: followed by base64. h1, SHA-256, is currently the only supported algorithm.

Downloaded modules are kept in the module cache, by default in $GOPATH/pkg/mod, or under GOMODCACHE if that is set.