225 lines
7.8 KiB
XML
225 lines
7.8 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";
|
|
};
|
|
|
|
vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />
|
|
|
|
subPackages = [ "." ]; <co xml:id='ex-buildGoModule-2' />
|
|
|
|
deleteVendor = true; <co xml:id='ex-buildGoModule-3' />
|
|
|
|
runVend = true; <co xml:id='ex-buildGoModule-4' />
|
|
|
|
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>vendorSha256</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>
|
|
<callout arearefs='ex-buildGoModule-3'>
|
|
<para>
|
|
<varname>deleteVendor</varname> removes the pre-existing vendor directory and fetches the dependencies. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs='ex-buildGoModule-4'>
|
|
<para>
|
|
<varname>runVend</varname> runs the vend command to generate the vendor directory. This is useful if your code depends on c code and go mod tidy does not include the needed sources to build.
|
|
</para>
|
|
</callout>
|
|
</calloutlist>
|
|
</para>
|
|
|
|
<para>
|
|
<varname>vendorSha256</varname> can also take <varname>null</varname> as an input.
|
|
|
|
When `null` is used as a value, rather than fetching the dependencies
|
|
and vendoring them, we use the vendoring included within the source repo.
|
|
If you'd like to not have to update this field on dependency changes,
|
|
run `go mod vendor` in your source repo and set 'vendorSha256 = null;'
|
|
</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' />
|
|
|
|
deleteVendor = true; <co xml:id='ex-buildGoPackage-4' />
|
|
|
|
buildFlags = [ "--tags" "release" ]; <co xml:id='ex-buildGoPackage-5' />
|
|
}
|
|
</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>deleteVendor</varname> removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
|
|
</para>
|
|
</callout>
|
|
<callout arearefs='ex-buildGoPackage-5'>
|
|
<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>
|
|
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>
|