pyrox.dev
1# Go {#sec-language-go}
2
3## Building Go modules with `buildGoModule` {#ssec-language-go}
4
5The function `buildGoModule` builds Go programs managed with Go modules. It builds [Go Modules](https://go.dev/wiki/Modules) through a two phase build:
6
7- An intermediate fetcher derivation called `goModules`. This derivation will be used to fetch all the dependencies of the Go module.
8- A final derivation will use the output of the intermediate derivation to build the binaries and produce the final output.
9
10### Example for `buildGoModule` {#ex-buildGoModule}
11
12The following is an example expression using `buildGoModule`:
13
14```nix
15{
16 pet = buildGoModule (finalAttrs: {
17 pname = "pet";
18 version = "0.3.4";
19
20 src = fetchFromGitHub {
21 owner = "knqyf263";
22 repo = "pet";
23 tag = "v${finalAttrs.version}";
24 hash = "sha256-Gjw1dRrgM8D3G7v6WIM2+50r4HmTXvx0Xxme2fH9TlQ=";
25 };
26
27 vendorHash = "sha256-ciBIR+a1oaYH+H1PcC8cD8ncfJczk1IiJ8iYNM+R6aA=";
28
29 meta = {
30 description = "Simple command-line snippet manager, written in Go";
31 homepage = "https://github.com/knqyf263/pet";
32 license = lib.licenses.mit;
33 maintainers = with lib.maintainers; [ kalbasit ];
34 };
35 });
36}
37```
38
39## Attributes of `buildGoModule` {#buildgomodule-parameters}
40
41Many attributes [controlling the build phase](#variables-controlling-the-build-phase) are respected by `buildGoModule`. Note that `buildGoModule` reads the following attributes also when building the `vendor/` goModules fixed output derivation as well:
42
43- [`sourceRoot`](#var-stdenv-sourceRoot)
44- [`prePatch`](#var-stdenv-prePatch)
45- [`patches`](#var-stdenv-patches)
46- [`patchFlags`](#var-stdenv-patchFlags)
47- [`postPatch`](#var-stdenv-postPatch)
48- [`preBuild`](#var-stdenv-preBuild)
49- `env`: useful for passing down variables such as `GOWORK`.
50
51To control test execution of the build derivation, the following attributes are of interest:
52
53- [`checkInputs`](#var-stdenv-checkInputs)
54- [`preCheck`](#var-stdenv-preCheck)
55- [`checkFlags`](#var-stdenv-checkFlags)
56
57In addition to the above attributes, and the many more variables respected also by `stdenv.mkDerivation`, `buildGoModule` respects Go-specific attributes that tweak them to behave slightly differently:
58
59### `vendorHash` {#var-go-vendorHash}
60
61Hash of the output of the intermediate fetcher derivation (the dependencies of the Go modules).
62
63`vendorHash` can be set to `null`.
64In that case, rather than fetching the dependencies, the dependencies already vendored in the `vendor` directory of the source repo will be used.
65
66To avoid updating this field when dependencies change, run `go mod vendor` in your source repo and set `vendorHash = null;`.
67You can read more about [vendoring in the Go documentation](https://go.dev/ref/mod#vendoring).
68
69To obtain the hash, set `vendorHash = lib.fakeHash;` and run the build. ([more details here](#sec-source-hashes)).
70Another way is to use `nix-prefetch` to obtain the hash. The following command gets the value of `vendorHash` for package `pet`:
71
72
73```sh
74cd path/to/nixpkgs
75nix-prefetch -E "{ sha256 }: ((import ./. { }).my-package.overrideAttrs { vendorHash = sha256; }).goModules"
76```
77
78`vendorHash` can be overridden with `overrideAttrs`. Override the above example like this:
79
80```nix
81{
82 pet_0_4_0 = pet.overrideAttrs (
83 finalAttrs: previousAttrs: {
84 version = "0.4.0";
85 src = fetchFromGitHub {
86 inherit (previousAttrs.src) owner repo;
87 rev = "v${finalAttrs.version}";
88 hash = "sha256-gVTpzmXekQxGMucDKskGi+e+34nJwwsXwvQTjRO6Gdg=";
89 };
90 vendorHash = "sha256-dUvp7FEW09V0xMuhewPGw3TuAic/sD7xyXEYviZ2Ivs=";
91 }
92 );
93}
94```
95
96### `proxyVendor` {#var-go-proxyVendor}
97
98If `true`, the intermediate fetcher downloads dependencies from the
99[Go module proxy](https://go.dev/ref/mod#module-proxy) (using `go mod download`) instead of vendoring them. The resulting
100[module cache](https://go.dev/ref/mod#module-cache) is then passed to the final derivation.
101
102This is useful if your code depends on C code and `go mod tidy` does not include the needed sources to build or
103if any dependency has case-insensitive conflicts which will produce platform-dependent `vendorHash` checksums.
104
105Defaults to `false`.
106
107
108### `modPostBuild` {#var-go-modPostBuild}
109
110Shell commands to run after the build of the goModules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash`.
111Note that if you change this attribute, you need to update the `vendorHash` attribute.
112
113
114### `modRoot` {#var-go-modRoot}
115
116The root directory of the Go module that contains the `go.mod` file.
117
118Defaults to `./`, which is the root of `src`.
119
120### `ldflags` {#var-go-ldflags}
121
122A string list of flags to pass to the Go linker tool via the `-ldflags` argument of `go build`. Possible values can be retrieved by running `go tool link --help`.
123The most common use case for this argument is to make the resulting executable aware of its own version by injecting the value of string variable using the `-X` flag. For example:
124
125```nix
126{
127 ldflags = [
128 "-X main.Version=${version}"
129 "-X main.Commit=${version}"
130 ];
131}
132```
133
134### `tags` {#var-go-tags}
135
136A string list of [Go build tags (also called build constraints)](https://pkg.go.dev/cmd/go#hdr-Build_constraints) that are passed via the `-tags` argument of `go build`. These constraints control whether Go files from the source should be included in the build. For example:
137
138```nix
139{
140 tags = [
141 "production"
142 "sqlite"
143 ];
144}
145```
146
147Tags can also be set conditionally:
148
149```nix
150{ tags = [ "production" ] ++ lib.optionals withSqlite [ "sqlite" ]; }
151```
152
153### `deleteVendor` {#var-go-deleteVendor}
154
155If set to `true`, removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
156
157### `subPackages` {#var-go-subPackages}
158
159Specified as a string or list of strings. Limits the builder from building child packages that have not been listed. If `subPackages` is not specified, all child packages will be built.
160
161Many Go projects keep the main package in a `cmd` directory.
162Following example could be used to only build the example-cli and example-server binaries:
163
164```nix
165{
166 subPackages = [
167 "cmd/example-cli"
168 "cmd/example-server"
169 ];
170}
171```
172
173### `excludedPackages` {#var-go-excludedPackages}
174
175Specified as a string or list of strings. Causes the builder to skip building child packages that match any of the provided values.
176
177### `enableParallelBuilding` {#var-go-enableParallelBuilding}
178
179Whether builds and tests should run in parallel.
180
181Defaults to `true`.
182
183### `allowGoReference` {#var-go-allowGoReference}
184
185Whether the build result should be allowed to contain references to the Go tool chain. This might be needed for programs that are coupled with the compiler, but shouldn't be set without a good reason.
186
187Defaults to `false`
188
189### `goSum` {#var-go-goSum}
190
191Specifies the contents of the `go.sum` file and triggers rebuilds when it changes. This helps combat inconsistent dependency errors on `go.sum` changes.
192
193Defaults to `null`
194
195### `buildTestBinaries` {#var-go-buildTestBinaries}
196
197This option allows to compile test binaries instead of the usual binaries produced by a package.
198Go can [compile test into binaries](https://pkg.go.dev/cmd/go#hdr-Test_packages) using the `go test -c` command.
199These binaries can then be executed at a later point (outside the Nix sandbox) to run the tests.
200This is mostly useful for downstream consumers to run integration or end-to-end tests that won't work in the Nix sandbox, for example because they require network access.
201
202## Versioned toolchains and builders {#ssec-go-toolchain-versions}
203
204Beside `buildGoModule`, there are also versioned builders available that pin a specific Go version, like `buildGo124Module` for Go 1.24.
205Similar, versioned toolchains are available, like `go_1_24` for Go 1.24.
206Both builder and toolchain of a certain version will be removed as soon as the Go version reaches its end of life.
207
208As toolchain updates in nixpkgs cause mass rebuilds and must go through the staging cycle, it can take a while until a new Go minor version is available to consumers of nixpkgs.
209If you want quicker access to the latest minor, use `go_latest` toolchain and `buildGoLatestModule` builder.
210To learn more about the Go maintenance and upgrade procedure in nixpkgs, check out the [Go toolchain/builder upgrade policy](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/go/README.md#go-toolchainbuilder-upgrade-policy).
211
212::: {.warning}
213The use of `go_latest` and `buildGoLatestModule` is restricted within nixpkgs.
214The [Go toolchain/builder upgrade policy](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/go/README.md#go-toolchainbuilder-upgrade-policy) must be followed.
215:::
216
217## Overriding `goModules` {#buildGoModule-goModules-override}
218
219Overriding `<pkg>.goModules` by calling `goModules.overrideAttrs` is unsupported. Still, it is possible to override the `vendorHash` (`goModules`'s `outputHash`) and the `pre`/`post` hooks for both the build and patch phases of the primary and `goModules` derivation.
220
221Alternatively, the primary derivation provides an overridable `passthru.overrideModAttrs` function to store the attribute overlay implicitly taken by `goModules.overrideAttrs`. Here's an example usage of `overrideModAttrs`:
222
223```nix
224{
225 pet-overridden = pet.overrideAttrs (
226 finalAttrs: previousAttrs: {
227 passthru = previousAttrs.passthru // {
228 # If the original package has an `overrideModAttrs` attribute set, you'd
229 # want to extend it, and not replace it. Hence we use
230 # `lib.composeExtensions`. If you are sure the `overrideModAttrs` of the
231 # original package trivially does nothing, you can safely replace it
232 # with your own by not using `lib.composeExtensions`.
233 overrideModAttrs = lib.composeExtensions previousAttrs.passthru.overrideModAttrs (
234 finalModAttrs: previousModAttrs: {
235 # goModules-specific overriding goes here
236 postBuild = ''
237 # Here you have access to the `vendor` directory.
238 substituteInPlace vendor/github.com/example/repo/file.go \
239 --replace-fail "panic(err)" ""
240 '';
241 }
242 );
243 };
244 }
245 );
246}
247```
248
249## Controlling the Go environment {#ssec-go-environment}
250
251The Go build can be further tweaked by setting environment variables via the `env` attribute. In most cases, this isn't needed. Possible values can be found in the [Go documentation of accepted environment variables](https://pkg.go.dev/cmd/go#hdr-Environment_variables). Notice that some of these flags are set by the build helper itself and should not be set explicitly. If in doubt, grep the implementation of the build helper.
252
253`buildGoModule` officially supports the following environment variables:
254
255### `env.CGO_ENABLED` {#var-go-CGO_ENABLED}
256
257When set to `0`, the [cgo](https://pkg.go.dev/cmd/cgo) command is disabled. As a consequence, the build
258program can't link against C libraries anymore, and the resulting binary is statically linked.
259
260When building with CGO enabled, Go will likely link some packages from the Go standard library against C libraries,
261even when the target code does not explicitly call into C dependencies. With `env.CGO_ENABLED = 0;`, Go
262will always use the Go native implementation of these internal packages. For reference see
263[net](https://pkg.go.dev/net#hdr-Name_Resolution) and [os/user](https://pkg.go.dev/os/user#pkg-overview) packages.
264Notice that the decision whether these packages should use native Go implementation or not can also be controlled
265on a per package level using build tags (`tags`). In case CGO is disabled, these tags have no additional effect.
266
267When a Go program depends on C libraries, place those dependencies in `buildInputs`:
268
269```nix
270{
271 buildInputs = [
272 libvirt
273 libxml2
274 ];
275}
276```
277
278`env.CGO_ENABLED` defaults to `1`.
279
280## Skipping tests {#ssec-skip-go-tests}
281
282`buildGoModule` runs tests by default. Failing tests can be disabled using the `checkFlags` parameter.
283This is done with the [`-skip` or `-run`](https://pkg.go.dev/cmd/go#hdr-Testing_flags) flags of the `go test` command.
284
285For example, only a selection of tests could be run with:
286
287```nix
288{
289 # -run and -skip accept regular expressions
290 checkFlags = [ "-run=^Test(Simple|Fast)$" ];
291}
292```
293
294If a larger amount of tests should be skipped, the following pattern can be used:
295
296```nix
297{
298 checkFlags =
299 let
300 # Skip tests that require network access
301 skippedTests = [
302 "TestNetwork"
303 "TestDatabase/with_mysql" # exclude only the subtest
304 "TestIntegration"
305 ];
306 in
307 [ "-skip=^${builtins.concatStringsSep "$|^" skippedTests}$" ];
308}
309```
310
311To disable tests altogether, set `doCheck = false;`.
312
313## Migrating from `buildGoPackage` to `buildGoModule` {#buildGoPackage-migration}
314
315::: {.warning}
316`buildGoPackage` was removed for the 25.05 release. It was used to build legacy Go programs
317that do not support Go modules.
318:::
319
320Go modules, released 6y ago, are now widely adopted in the ecosystem.
321Most upstream projects are using Go modules, and the tooling previously used for dependency management in Go is mostly deprecated, archived or at least unmaintained at this point.
322
323In case a project doesn't have external dependencies or dependencies are vendored in a way understood by `go mod init`, migration can be done with a few changes in the package.
324
325- Switch the builder from `buildGoPackage` to `buildGoModule`
326- Remove `goPackagePath` and other attributes specific to `buildGoPackage`
327- Set `vendorHash = null;`
328- Run `go mod init <module name>` in `postPatch`
329
330In case the package has external dependencies that aren't vendored or the build setup is more complex the upstream source might need to be patched.
331Examples for the migration can be found in the [issue tracking migration within nixpkgs](https://github.com/NixOS/nixpkgs/issues/318069).