diff options
Diffstat (limited to 'doc/languages-frameworks/go.xml')
-rw-r--r-- | doc/languages-frameworks/go.xml | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml new file mode 100644 index 0000000000000..89908b3b8ff5c --- /dev/null +++ b/doc/languages-frameworks/go.xml @@ -0,0 +1,124 @@ +<section xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id="sec-language-go"> + +<title>Go</title> + +<para>The function <varname>buildGoPackage</varname> builds +standard Go packages. +</para> + +<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title> +<programlisting> +net = buildGoPackage rec { + name = "go.net-${rev}"; + goPackagePath = "golang.org/x/net"; <co xml:id='ex-buildGoPackage-1' /> + subPackages = [ "ipv4" "ipv6" ]; <co xml:id='ex-buildGoPackage-2' /> + rev = "e0403b4e005"; + src = fetchFromGitHub { + inherit rev; + owner = "golang"; + repo = "net"; + sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp"; + }; + goPackageAliases = [ "code.google.com/p/go.net" ]; <co xml:id='ex-buildGoPackage-3' /> + propagatedBuildInputs = [ goPackages.text ]; <co xml:id='ex-buildGoPackage-4' /> + buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-5' /> + disabled = isGo13;<co xml:id='ex-buildGoPackage-6' /> +}; +</programlisting> +</example> + +<para><xref linkend='ex-buildGoPackage'/> is an example expression using buildGoPackage, +the following arguments are of special significance to the function: + +<calloutlist> + + <callout arearefs='ex-buildGoPackage-1'> + <para> + <varname>goPackagePath</varname> specifies the package's canonical Go import path. + </para> + </callout> + + <callout arearefs='ex-buildGoPackage-2'> + <para> + <varname>subPackages</varname> limits the builder from building child packages that + have not been listed. If <varname>subPackages</varname> is not specified, all child + packages will be built. + </para> + <para> + In this example only <literal>code.google.com/p/go.net/ipv4</literal> and + <literal>code.google.com/p/go.net/ipv6</literal> will be built. + </para> + </callout> + + <callout arearefs='ex-buildGoPackage-3'> + <para> + <varname>goPackageAliases</varname> is a list of alternative import paths + that are valid for this library. + Packages that depend on this library will automatically rename + import paths that match any of the aliases to <literal>goPackagePath</literal>. + </para> + <para> + In this example imports will be renamed from + <literal>code.google.com/p/go.net</literal> to + <literal>golang.org/x/net</literal> in every package that depend on the + <literal>go.net</literal> library. + </para> + </callout> + + <callout arearefs='ex-buildGoPackage-4'> + <para> + <varname>propagatedBuildInputs</varname> is where the dependencies of a Go library are + listed. Only libraries should list <varname>propagatedBuildInputs</varname>. If a standalone + program is being built instead, use <varname>buildInputs</varname>. If a library's tests require + additional dependencies that are not propagated, they should be listed in <varname>buildInputs</varname>. + </para> + </callout> + + <callout arearefs='ex-buildGoPackage-5'> + <para> + <varname>buildFlags</varname> is a list of flags passed to the go build command. + </para> + </callout> + + <callout arearefs='ex-buildGoPackage-6'> + <para> + If <varname>disabled</varname> is <literal>true</literal>, + nix will refuse to build this package. + </para> + <para> + In this example the package will not be built for go 1.3. The <literal>isGo13</literal> + is an utility function that returns <literal>true</literal> if go used to build the + package has version 1.3.x. + </para> + </callout> + +</calloutlist> + +</para> + +<para> +Reusable Go libraries may be found in the <varname>goPackages</varname> set. You can test +build a Go package as follows: + +<screen> +$ nix-build -A goPackages.net +</screen> + +</para> + +<para> +You may use Go packages installed into the active Nix profiles by adding +the following to your ~/.bashrc: + +<screen> +for p in $NIX_PROFILES; do + GOPATH="$p/share/go:$GOPATH" +done +</screen> +</para> + + <para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/cstrahan/go2nix">go2nix</link>.</para> +</section> + |