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