tjh.dev
1<section xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xml:id="sec-language-go">
4 <title>Go</title>
5
6 <section xml:id="ssec-go-modules">
7 <title>Go modules</title>
8
9 <para>
10 The function <varname> buildGoModule </varname> builds Go programs managed
11 with Go modules. It builds a
12 <link xlink:href="https://github.com/golang/go/wiki/Modules">Go
13 modules</link> through a two phase build:
14 <itemizedlist>
15 <listitem>
16 <para>
17 An intermediate fetcher derivation. This derivation will be used to fetch
18 all of the dependencies of the Go module.
19 </para>
20 </listitem>
21 <listitem>
22 <para>
23 A final derivation will use the output of the intermediate derivation to
24 build the binaries and produce the final output.
25 </para>
26 </listitem>
27 </itemizedlist>
28 </para>
29
30 <example xml:id='ex-buildGoModule'>
31 <title>buildGoModule</title>
32<programlisting>
33pet = buildGoModule rec {
34 name = "pet-${version}";
35 version = "0.3.4";
36
37 src = fetchFromGitHub {
38 owner = "knqyf263";
39 repo = "pet";
40 rev = "v${version}";
41 sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
42 };
43
44 modSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
45
46 subPackages = [ "." ]; <co xml:id='ex-buildGoModule-2' />
47
48 meta = with lib; {
49 description = "Simple command-line snippet manager, written in Go";
50 homepage = https://github.com/knqyf263/pet;
51 license = licenses.mit;
52 maintainers = with maintainers; [ kalbasit ];
53 platforms = platforms.linux ++ platforms.darwin;
54 };
55}
56</programlisting>
57 </example>
58
59 <para>
60 <xref linkend='ex-buildGoModule'/> is an example expression using
61 buildGoModule, the following arguments are of special significance to the
62 function:
63 <calloutlist>
64 <callout arearefs='ex-buildGoModule-1'>
65 <para>
66 <varname>modSha256</varname> is the hash of the output of the
67 intermediate fetcher derivation.
68 </para>
69 </callout>
70 <callout arearefs='ex-buildGoModule-2'>
71 <para>
72 <varname>subPackages</varname> limits the builder from building child
73 packages that have not been listed. If <varname>subPackages</varname> is
74 not specified, all child packages will be built.
75 </para>
76 </callout>
77 </calloutlist>
78 </para>
79 </section>
80
81 <section xml:id="ssec-go-legacy">
82 <title>Go legacy</title>
83
84 <para>
85 The function <varname> buildGoPackage </varname> builds legacy Go programs,
86 not supporting Go modules.
87 </para>
88
89 <example xml:id='ex-buildGoPackage'>
90 <title>buildGoPackage</title>
91<programlisting>
92deis = buildGoPackage rec {
93 name = "deis-${version}";
94 version = "1.13.0";
95
96 goPackagePath = "github.com/deis/deis"; <co xml:id='ex-buildGoPackage-1' />
97 subPackages = [ "client" ]; <co xml:id='ex-buildGoPackage-2' />
98
99 src = fetchFromGitHub {
100 owner = "deis";
101 repo = "deis";
102 rev = "v${version}";
103 sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
104 };
105
106 goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-3' />
107
108 buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-4' />
109}
110</programlisting>
111 </example>
112
113 <para>
114 <xref linkend='ex-buildGoPackage'/> is an example expression using
115 buildGoPackage, the following arguments are of special significance to the
116 function:
117 <calloutlist>
118 <callout arearefs='ex-buildGoPackage-1'>
119 <para>
120 <varname>goPackagePath</varname> specifies the package's canonical Go
121 import path.
122 </para>
123 </callout>
124 <callout arearefs='ex-buildGoPackage-2'>
125 <para>
126 <varname>subPackages</varname> limits the builder from building child
127 packages that have not been listed. If <varname>subPackages</varname> is
128 not specified, all child packages will be built.
129 </para>
130 <para>
131 In this example only <literal>github.com/deis/deis/client</literal> will
132 be built.
133 </para>
134 </callout>
135 <callout arearefs='ex-buildGoPackage-3'>
136 <para>
137 <varname>goDeps</varname> is where the Go dependencies of a Go program
138 are listed as a list of package source identified by Go import path. It
139 could be imported as a separate <varname>deps.nix</varname> file for
140 readability. The dependency data structure is described below.
141 </para>
142 </callout>
143 <callout arearefs='ex-buildGoPackage-4'>
144 <para>
145 <varname>buildFlags</varname> is a list of flags passed to the go build
146 command.
147 </para>
148 </callout>
149 </calloutlist>
150 </para>
151
152 <para>
153 The <varname>goDeps</varname> attribute can be imported from a separate
154 <varname>nix</varname> file that defines which Go libraries are needed and
155 should be included in <varname>GOPATH</varname> for
156 <varname>buildPhase</varname>.
157 </para>
158
159 <example xml:id='ex-goDeps'>
160 <title>deps.nix</title>
161<programlisting>
162[ <co xml:id='ex-goDeps-1' />
163 {
164 goPackagePath = "gopkg.in/yaml.v2"; <co xml:id='ex-goDeps-2' />
165 fetch = {
166 type = "git"; <co xml:id='ex-goDeps-3' />
167 url = "https://gopkg.in/yaml.v2";
168 rev = "a83829b6f1293c91addabc89d0571c246397bbf4";
169 sha256 = "1m4dsmk90sbi17571h6pld44zxz7jc4lrnl4f27dpd1l8g5xvjhh";
170 };
171 }
172 {
173 goPackagePath = "github.com/docopt/docopt-go";
174 fetch = {
175 type = "git";
176 url = "https://github.com/docopt/docopt-go";
177 rev = "784ddc588536785e7299f7272f39101f7faccc3f";
178 sha256 = "0wwz48jl9fvl1iknvn9dqr4gfy1qs03gxaikrxxp9gry6773v3sj";
179 };
180 }
181]
182</programlisting>
183 </example>
184
185 <para>
186 <calloutlist>
187 <callout arearefs='ex-goDeps-1'>
188 <para>
189 <varname>goDeps</varname> is a list of Go dependencies.
190 </para>
191 </callout>
192 <callout arearefs='ex-goDeps-2'>
193 <para>
194 <varname>goPackagePath</varname> specifies Go package import path.
195 </para>
196 </callout>
197 <callout arearefs='ex-goDeps-3'>
198 <para>
199 <varname>fetch type</varname> that needs to be used to get package
200 source. If <varname>git</varname> is used there should be
201 <varname>url</varname>, <varname>rev</varname> and
202 <varname>sha256</varname> defined next to it.
203 </para>
204 </callout>
205 </calloutlist>
206 </para>
207
208 <para>
209 To extract dependency information from a Go package in automated way use
210 <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. It can
211 produce complete derivation and <varname>goDeps</varname> file for Go
212 programs.
213 </para>
214
215 <para>
216 <varname>buildGoPackage</varname> produces
217 <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where
218 <varname>bin</varname> includes program binaries. You can test build a Go
219 binary as follows:
220<screen>
221 $ nix-build -A deis.bin
222 </screen>
223 or build all outputs with:
224<screen>
225 $ nix-build -A deis.all
226 </screen>
227 <varname>bin</varname> output will be installed by default with
228 <varname>nix-env -i</varname> or <varname>systemPackages</varname>.
229 </para>
230
231 <para>
232 You may use Go packages installed into the active Nix profiles by adding the
233 following to your ~/.bashrc:
234<screen>
235for p in $NIX_PROFILES; do
236 GOPATH="$p/share/go:$GOPATH"
237done
238</screen>
239 </para>
240 </section>
241</section>