diff options
Diffstat (limited to 'nixpkgs/doc/languages-frameworks/go.xml')
| -rw-r--r-- | nixpkgs/doc/languages-frameworks/go.xml | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/nixpkgs/doc/languages-frameworks/go.xml b/nixpkgs/doc/languages-frameworks/go.xml new file mode 100644 index 00000000000..eee4706e551 --- /dev/null +++ b/nixpkgs/doc/languages-frameworks/go.xml @@ -0,0 +1,210 @@ +<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' /> + + runVend = true; <co xml:id='ex-buildGoModule-3' /> + + 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>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' /> + + 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> + 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> |