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 packages.
9</para>
10
11<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
12<programlisting>
13net = buildGoPackage rec {
14 name = "go.net-${rev}";
15 goPackagePath = "golang.org/x/net"; <co xml:id='ex-buildGoPackage-1' />
16 subPackages = [ "ipv4" "ipv6" ]; <co xml:id='ex-buildGoPackage-2' />
17 rev = "e0403b4e005";
18 src = fetchFromGitHub {
19 inherit rev;
20 owner = "golang";
21 repo = "net";
22 sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
23 };
24 goPackageAliases = [ "code.google.com/p/go.net" ]; <co xml:id='ex-buildGoPackage-3' />
25 propagatedBuildInputs = [ goPackages.text ]; <co xml:id='ex-buildGoPackage-4' />
26 buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-5' />
27 disabled = isGo13;<co xml:id='ex-buildGoPackage-6' />
28};
29</programlisting>
30</example>
31
32<para><xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage,
33the following arguments are of special significance to the function:
34
35<calloutlist>
36
37 <callout arearefs='ex-buildGoPackage-1'>
38 <para>
39 <varname>goPackagePath</varname> specifies the package's canonical Go import path.
40 </para>
41 </callout>
42
43 <callout arearefs='ex-buildGoPackage-2'>
44 <para>
45 <varname>subPackages</varname> limits the builder from building child packages that
46 have not been listed. If <varname>subPackages</varname> is not specified, all child
47 packages will be built.
48 </para>
49 <para>
50 In this example only <literal>code.google.com/p/go.net/ipv4</literal> and
51 <literal>code.google.com/p/go.net/ipv6</literal> will be built.
52 </para>
53 </callout>
54
55 <callout arearefs='ex-buildGoPackage-3'>
56 <para>
57 <varname>goPackageAliases</varname> is a list of alternative import paths
58 that are valid for this library.
59 Packages that depend on this library will automatically rename
60 import paths that match any of the aliases to <literal>goPackagePath</literal>.
61 </para>
62 <para>
63 In this example imports will be renamed from
64 <literal>code.google.com/p/go.net</literal> to
65 <literal>golang.org/x/net</literal> in every package that depend on the
66 <literal>go.net</literal> library.
67 </para>
68 </callout>
69
70 <callout arearefs='ex-buildGoPackage-4'>
71 <para>
72 <varname>propagatedBuildInputs</varname> is where the dependencies of a Go library are
73 listed. Only libraries should list <varname>propagatedBuildInputs</varname>. If a standalone
74 program is being built instead, use <varname>buildInputs</varname>. If a library's tests require
75 additional dependencies that are not propagated, they should be listed in <varname>buildInputs</varname>.
76 </para>
77 </callout>
78
79 <callout arearefs='ex-buildGoPackage-5'>
80 <para>
81 <varname>buildFlags</varname> is a list of flags passed to the go build command.
82 </para>
83 </callout>
84
85 <callout arearefs='ex-buildGoPackage-6'>
86 <para>
87 If <varname>disabled</varname> is <literal>true</literal>,
88 nix will refuse to build this package.
89 </para>
90 <para>
91 In this example the package will not be built for go 1.3. The <literal>isGo13</literal>
92 is an utility function that returns <literal>true</literal> if go used to build the
93 package has version 1.3.x.
94 </para>
95 </callout>
96
97</calloutlist>
98
99</para>
100
101<para>
102Reusable Go libraries may be found in the <varname>goPackages</varname> set. You can test
103build a Go package as follows:
104
105<screen>
106$ nix-build -A goPackages.net
107</screen>
108
109</para>
110
111<para>
112You may use Go packages installed into the active Nix profiles by adding
113the following to your ~/.bashrc:
114
115<screen>
116for p in $NIX_PROFILES; do
117 GOPATH="$p/share/go:$GOPATH"
118done
119</screen>
120</para>
121
122 <para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/cstrahan/go2nix">go2nix</link>.</para>
123</section>
124