pyrox.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
5<title>Go</title>
6
7<para>The function <varname>buildGoPackage</varname> builds
8standard Go programs.
9</para>
10
11<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
12<programlisting>
13deis = buildGoPackage rec {
14 name = "deis-${version}";
15 version = "1.13.0";
16
17 goPackagePath = "github.com/deis/deis"; <co xml:id='ex-buildGoPackage-1' />
18 subPackages = [ "client" ]; <co xml:id='ex-buildGoPackage-2' />
19
20 src = fetchFromGitHub {
21 owner = "deis";
22 repo = "deis";
23 rev = "v${version}";
24 sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
25 };
26
27 goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-3' />
28
29 buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-4' />
30}
31</programlisting>
32</example>
33
34<para><xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage,
35the following arguments are of special significance to the function:
36
37<calloutlist>
38
39 <callout arearefs='ex-buildGoPackage-1'>
40 <para>
41 <varname>goPackagePath</varname> specifies the package's canonical Go import path.
42 </para>
43 </callout>
44
45 <callout arearefs='ex-buildGoPackage-2'>
46 <para>
47 <varname>subPackages</varname> limits the builder from building child packages that
48 have not been listed. If <varname>subPackages</varname> is not specified, all child
49 packages will be built.
50 </para>
51 <para>
52 In this example only <literal>github.com/deis/deis/client</literal> will be built.
53 </para>
54 </callout>
55
56 <callout arearefs='ex-buildGoPackage-3'>
57 <para>
58 <varname>goDeps</varname> is where the Go dependencies of a Go program are listed
59 as a list of package source identified by Go import path.
60 It could be imported as a separate <varname>deps.nix</varname> file for
61 readability. The dependency data structure is described below.
62 </para>
63 </callout>
64
65 <callout arearefs='ex-buildGoPackage-4'>
66 <para>
67 <varname>buildFlags</varname> is a list of flags passed to the go build command.
68 </para>
69 </callout>
70
71</calloutlist>
72
73</para>
74
75<para>The <varname>goDeps</varname> attribute can be imported from a separate
76 <varname>nix</varname> file that defines which Go libraries are needed and should
77 be included in <varname>GOPATH</varname> for <varname>buildPhase</varname>.
78</para>
79
80<example xml:id='ex-goDeps'><title>deps.nix</title>
81<programlisting>
82[ <co xml:id='ex-goDeps-1' />
83 {
84 goPackagePath = "gopkg.in/yaml.v2"; <co xml:id='ex-goDeps-2' />
85 fetch = {
86 type = "git"; <co xml:id='ex-goDeps-3' />
87 url = "https://gopkg.in/yaml.v2";
88 rev = "a83829b6f1293c91addabc89d0571c246397bbf4";
89 sha256 = "1m4dsmk90sbi17571h6pld44zxz7jc4lrnl4f27dpd1l8g5xvjhh";
90 };
91 }
92 {
93 goPackagePath = "github.com/docopt/docopt-go";
94 fetch = {
95 type = "git";
96 url = "https://github.com/docopt/docopt-go";
97 rev = "784ddc588536785e7299f7272f39101f7faccc3f";
98 sha256 = "0wwz48jl9fvl1iknvn9dqr4gfy1qs03gxaikrxxp9gry6773v3sj";
99 };
100 }
101]
102</programlisting>
103</example>
104
105<para>
106
107<calloutlist>
108
109 <callout arearefs='ex-goDeps-1'>
110 <para>
111 <varname>goDeps</varname> is a list of Go dependencies.
112 </para>
113 </callout>
114
115 <callout arearefs='ex-goDeps-2'>
116 <para>
117 <varname>goPackagePath</varname> specifies Go package import path.
118 </para>
119 </callout>
120
121 <callout arearefs='ex-goDeps-3'>
122 <para>
123 <varname>fetch type</varname> that needs to be used to get package source. If <varname>git</varname>
124 is used there should be <varname>url</varname>, <varname>rev</varname> and <varname>sha256</varname>
125 defined next to it.
126 </para>
127 </callout>
128
129</calloutlist>
130
131</para>
132
133<para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>.
134 It can produce complete derivation and <varname>goDeps</varname> file for Go programs.</para>
135
136<para>
137 <varname>buildGoPackage</varname> produces <xref linkend='chap-multiple-output' xrefstyle="select: title" />
138 where <varname>bin</varname> includes program binaries. You can test build a Go binary as follows:
139
140 <screen>
141 $ nix-build -A deis.bin
142 </screen>
143
144 or build all outputs with:
145
146 <screen>
147 $ nix-build -A deis.all
148 </screen>
149
150 <varname>bin</varname> output will be installed by default with <varname>nix-env -i</varname>
151 or <varname>systemPackages</varname>.
152
153</para>
154
155<para>
156You may use Go packages installed into the active Nix profiles by adding
157the following to your ~/.bashrc:
158
159<screen>
160for p in $NIX_PROFILES; do
161 GOPATH="$p/share/go:$GOPATH"
162done
163</screen>
164</para>
165
166</section>