pyrox.dev
1# Go {#sec-language-go}
2
3## Go modules {#ssec-language-go}
4
5The function `buildGoModule` builds Go programs managed with Go modules. It builds a [Go Modules](https://github.com/golang/go/wiki/Modules) through a two phase build:
6
7- An intermediate fetcher derivation. This derivation will be used to fetch all of 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
12In the following is an example expression using `buildGoModule`, the following arguments are of special significance to the function:
13
14- `vendorHash`: is the hash of the output of the intermediate fetcher derivation.
15
16 `vendorHash` can also be set to `null`.
17 In that case, rather than fetching the dependencies and vendoring them, the dependencies vendored in the source repo will be used.
18
19 To avoid updating this field when dependencies change, run `go mod vendor` in your source repo and set `vendorHash = null;`
20
21 To obtain the actual hash, set `vendorHash = lib.fakeHash;` and run the build ([more details here](#sec-source-hashes)).
22- `proxyVendor`: Fetches (go mod download) and proxies the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build or if any dependency has case-insensitive conflicts which will produce platform-dependent `vendorHash` checksums.
23- `modPostBuild`: Shell commands to run after the build of the goModules executes `go mod vendor`, and before calculating fixed output derivation's `vendorHash`. Note that if you change this attribute, you need to update `vendorHash` attribute.
24
25```nix
26pet = buildGoModule rec {
27 pname = "pet";
28 version = "0.3.4";
29
30 src = fetchFromGitHub {
31 owner = "knqyf263";
32 repo = "pet";
33 rev = "v${version}";
34 hash = "sha256-Gjw1dRrgM8D3G7v6WIM2+50r4HmTXvx0Xxme2fH9TlQ=";
35 };
36
37 vendorHash = "sha256-ciBIR+a1oaYH+H1PcC8cD8ncfJczk1IiJ8iYNM+R6aA=";
38
39 meta = with lib; {
40 description = "Simple command-line snippet manager, written in Go";
41 homepage = "https://github.com/knqyf263/pet";
42 license = licenses.mit;
43 maintainers = with maintainers; [ kalbasit ];
44 };
45}
46```
47
48## `buildGoPackage` (legacy) {#ssec-go-legacy}
49
50The function `buildGoPackage` builds legacy Go programs, not supporting Go modules.
51
52### Example for `buildGoPackage` {#example-for-buildgopackage}
53
54In the following is an example expression using buildGoPackage, the following arguments are of special significance to the function:
55
56- `goPackagePath` specifies the package's canonical Go import path.
57- `goDeps` is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate `deps.nix` file for readability. The dependency data structure is described below.
58
59```nix
60deis = buildGoPackage rec {
61 pname = "deis";
62 version = "1.13.0";
63
64 goPackagePath = "github.com/deis/deis";
65
66 src = fetchFromGitHub {
67 owner = "deis";
68 repo = "deis";
69 rev = "v${version}";
70 hash = "sha256-XCPD4LNWtAd8uz7zyCLRfT8rzxycIUmTACjU03GnaeM=";
71 };
72
73 goDeps = ./deps.nix;
74}
75```
76
77The `goDeps` attribute can be imported from a separate `nix` file that defines which Go libraries are needed and should be included in `GOPATH` for `buildPhase`:
78
79```nix
80# deps.nix
81[ # goDeps is a list of Go dependencies.
82 {
83 # goPackagePath specifies Go package import path.
84 goPackagePath = "gopkg.in/yaml.v2";
85 fetch = {
86 # `fetch type` that needs to be used to get package source.
87 # If `git` is used there should be `url`, `rev` and `hash` defined next to it.
88 type = "git";
89 url = "https://gopkg.in/yaml.v2";
90 rev = "a83829b6f1293c91addabc89d0571c246397bbf4";
91 hash = "sha256-EMrdy0M0tNuOcITaTAmT5/dPSKPXwHDKCXFpkGbVjdQ=";
92 };
93 }
94 {
95 goPackagePath = "github.com/docopt/docopt-go";
96 fetch = {
97 type = "git";
98 url = "https://github.com/docopt/docopt-go";
99 rev = "784ddc588536785e7299f7272f39101f7faccc3f";
100 hash = "sha256-Uo89zjE+v3R7zzOq/gbQOHj3SMYt2W1nDHS7RCUin3M=";
101 };
102 }
103]
104```
105
106To extract dependency information from a Go package in automated way use [go2nix](https://github.com/kamilchm/go2nix). It can produce complete derivation and `goDeps` file for Go programs.
107
108You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc:
109
110```bash
111for p in $NIX_PROFILES; do
112 GOPATH="$p/share/go:$GOPATH"
113done
114```
115
116## Attributes used by the builders {#ssec-go-common-attributes}
117
118Many attributes [controlling the build phase](#variables-controlling-the-build-phase) are respected by both `buildGoModule` and `buildGoPackage`. Note that `buildGoModule` reads the following attributes also when building the `vendor/` goModules fixed output derivation as well:
119
120- [`sourceRoot`](#var-stdenv-sourceRoot)
121- [`prePatch`](#var-stdenv-prePatch)
122- [`patches`](#var-stdenv-patches)
123- [`patchFlags`](#var-stdenv-patchFlags)
124- [`postPatch`](#var-stdenv-postPatch)
125- [`preBuild`](#var-stdenv-preBuild)
126
127In addition to the above attributes, and the many more variables respected also by `stdenv.mkDerivation`, both `buildGoModule` and `buildGoPackage` respect Go-specific attributes that tweak them to behave slightly differently:
128
129### `ldflags` {#var-go-ldflags}
130
131Arguments to pass to the Go linker tool via the `-ldflags` argument of `go build`. The most common use case for this argument is to make the resulting executable aware of its own version. For example:
132
133```nix
134 ldflags = [
135 "-s" "-w"
136 "-X main.Version=${version}"
137 "-X main.Commit=${version}"
138 ];
139```
140
141### `tags` {#var-go-tags}
142
143Arguments to pass to the Go via the `-tags` argument of `go build`. For example:
144
145```nix
146 tags = [
147 "production"
148 "sqlite"
149 ];
150```
151
152```nix
153 tags = [ "production" ] ++ lib.optionals withSqlite [ "sqlite" ];
154```
155
156### `deleteVendor` {#var-go-deleteVendor}
157
158Removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
159
160### `subPackages` {#var-go-subPackages}
161
162Specified 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.
163
164### `excludedPackages` {#var-go-excludedPackages}
165
166Specified as a string or list of strings. Causes the builder to skip building child packages that match any of the provided values. If `excludedPackages` is not specified, all child packages will be built.