f373ecec8f
When modSha256 is null, disable the nix sandbox instead of using a fixed-output derivation. This requires the nix-daemon to have `sandbox = relaxed` set in their config to work properly. Because the output is (hopefully) deterministic based on the inputs, this should give a reproducible output. This is useful for development outside of nixpkgs where re-generating the modSha256 on each mod.sum changes is cumbersome. Don't use this in nixpkgs! This is why null is not the default value.
215 lines
7.4 KiB
XML
215 lines
7.4 KiB
XML
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink"
|
|
xml:id="sec-language-go">
|
|
<title>Go</title>
|
|
|
|
<section xml:id="ssec-go-modules">
|
|
<title>Go modules</title>
|
|
|
|
<para>
|
|
The function <varname> buildGoModule </varname> builds Go programs managed with Go modules. It builds a <link xlink:href="https://github.com/golang/go/wiki/Modules">Go modules</link> through a two phase build:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
An intermediate fetcher derivation. This derivation will be used to fetch all of the dependencies of the Go module.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A final derivation will use the output of the intermediate derivation to build the binaries and produce the final output.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<example xml:id='ex-buildGoModule'>
|
|
<title>buildGoModule</title>
|
|
<programlisting>
|
|
pet = buildGoModule rec {
|
|
pname = "pet";
|
|
version = "0.3.4";
|
|
|
|
src = fetchFromGitHub {
|
|
owner = "knqyf263";
|
|
repo = "pet";
|
|
rev = "v${version}";
|
|
sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
|
|
};
|
|
|
|
modSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
|
|
|
|
subPackages = [ "." ]; <co xml:id='ex-buildGoModule-2' />
|
|
|
|
meta = with lib; {
|
|
description = "Simple command-line snippet manager, written in Go";
|
|
homepage = https://github.com/knqyf263/pet;
|
|
license = licenses.mit;
|
|
maintainers = with maintainers; [ kalbasit ];
|
|
platforms = platforms.linux ++ platforms.darwin;
|
|
};
|
|
}
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
<xref linkend='ex-buildGoModule'/> is an example expression using buildGoModule, the following arguments are of special significance to the function:
|
|
<calloutlist>
|
|
<callout arearefs='ex-buildGoModule-1'>
|
|
<para>
|
|
<varname>modSha256</varname> is the hash of the output of the intermediate fetcher derivation.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs='ex-buildGoModule-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>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
|
|
<para>
|
|
<varname>modSha256</varname> can also take <varname>null</varname> as an input.
|
|
|
|
When `null` is used as a value, the derivation won't be a
|
|
fixed-output derivation but disable the build sandbox instead. This can be useful outside
|
|
of nixpkgs where re-generating the modSha256 on each mod.sum changes is cumbersome,
|
|
but will fail to build by Hydra, as builds with a disabled sandbox are discouraged.
|
|
</para>
|
|
</section>
|
|
|
|
<section xml:id="ssec-go-legacy">
|
|
<title>Go legacy</title>
|
|
|
|
<para>
|
|
The function <varname> buildGoPackage </varname> builds legacy Go programs, not supporting Go modules.
|
|
</para>
|
|
|
|
<example xml:id='ex-buildGoPackage'>
|
|
<title>buildGoPackage</title>
|
|
<programlisting>
|
|
deis = buildGoPackage rec {
|
|
pname = "deis";
|
|
version = "1.13.0";
|
|
|
|
goPackagePath = "github.com/deis/deis"; <co xml:id='ex-buildGoPackage-1' />
|
|
subPackages = [ "client" ]; <co xml:id='ex-buildGoPackage-2' />
|
|
|
|
src = fetchFromGitHub {
|
|
owner = "deis";
|
|
repo = "deis";
|
|
rev = "v${version}";
|
|
sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
|
|
};
|
|
|
|
goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-3' />
|
|
|
|
buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-4' />
|
|
}
|
|
</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>github.com/deis/deis/client</literal> will be built.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs='ex-buildGoPackage-3'>
|
|
<para>
|
|
<varname>goDeps</varname> is where the Go dependencies of a Go program are listed as a list of package source identified by Go import path. It could be imported as a separate <varname>deps.nix</varname> file for readability. The dependency data structure is described below.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs='ex-buildGoPackage-4'>
|
|
<para>
|
|
<varname>buildFlags</varname> is a list of flags passed to the go build command.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
|
|
<para>
|
|
The <varname>goDeps</varname> attribute can be imported from a separate <varname>nix</varname> file that defines which Go libraries are needed and should be included in <varname>GOPATH</varname> for <varname>buildPhase</varname>.
|
|
</para>
|
|
|
|
<example xml:id='ex-goDeps'>
|
|
<title>deps.nix</title>
|
|
<programlisting>
|
|
[ <co xml:id='ex-goDeps-1' />
|
|
{
|
|
goPackagePath = "gopkg.in/yaml.v2"; <co xml:id='ex-goDeps-2' />
|
|
fetch = {
|
|
type = "git"; <co xml:id='ex-goDeps-3' />
|
|
url = "https://gopkg.in/yaml.v2";
|
|
rev = "a83829b6f1293c91addabc89d0571c246397bbf4";
|
|
sha256 = "1m4dsmk90sbi17571h6pld44zxz7jc4lrnl4f27dpd1l8g5xvjhh";
|
|
};
|
|
}
|
|
{
|
|
goPackagePath = "github.com/docopt/docopt-go";
|
|
fetch = {
|
|
type = "git";
|
|
url = "https://github.com/docopt/docopt-go";
|
|
rev = "784ddc588536785e7299f7272f39101f7faccc3f";
|
|
sha256 = "0wwz48jl9fvl1iknvn9dqr4gfy1qs03gxaikrxxp9gry6773v3sj";
|
|
};
|
|
}
|
|
]
|
|
</programlisting>
|
|
</example>
|
|
|
|
<para>
|
|
<calloutlist>
|
|
<callout arearefs='ex-goDeps-1'>
|
|
<para>
|
|
<varname>goDeps</varname> is a list of Go dependencies.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs='ex-goDeps-2'>
|
|
<para>
|
|
<varname>goPackagePath</varname> specifies Go package import path.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs='ex-goDeps-3'>
|
|
<para>
|
|
<varname>fetch type</varname> that needs to be used to get package source. If <varname>git</varname> is used there should be <varname>url</varname>, <varname>rev</varname> and <varname>sha256</varname> defined next to it.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
|
|
<para>
|
|
To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>. It can produce complete derivation and <varname>goDeps</varname> file for Go programs.
|
|
</para>
|
|
|
|
<para>
|
|
<varname>buildGoPackage</varname> produces <xref linkend='chap-multiple-output' xrefstyle="select: title" /> where <varname>bin</varname> includes program binaries. You can test build a Go binary as follows:
|
|
<screen>
|
|
<prompt>$ </prompt>nix-build -A deis.bin
|
|
</screen>
|
|
or build all outputs with:
|
|
<screen>
|
|
<prompt>$ </prompt>nix-build -A deis.all
|
|
</screen>
|
|
<varname>bin</varname> output will be installed by default with <varname>nix-env -i</varname> or <varname>systemPackages</varname>.
|
|
</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>
|
|
</section>
|
|
</section>
|