diff options
author | Wael M. Nasreddine <wael.nasreddine@gmail.com> | 2019-03-08 11:17:05 -0800 |
---|---|---|
committer | Wael M. Nasreddine <wael.nasreddine@gmail.com> | 2019-03-14 10:31:02 -0700 |
commit | 28435e47b149623dd55b83aee3b016063d9d391b (patch) | |
tree | 6dc9aed01177501cd3ab08c887c13ec5be4e71e3 /doc/languages-frameworks | |
parent | a0d835e95d3e99d57e14adc6116e2b498f32f323 (diff) |
buildGoModule: function for packaging Go modules
The function buildGoModule builds Go programs managed with Go modules. It builds a Go module through a two phase build: - An intermediate fetcher derivation. This derivation will be used to fetch all of the dependencies of the Go module. - A final derivation will use the output of the intermediate derivation to build the binaries and produce the final output.
Diffstat (limited to 'doc/languages-frameworks')
-rw-r--r-- | doc/languages-frameworks/go.xml | 279 |
1 files changed, 180 insertions, 99 deletions
diff --git a/doc/languages-frameworks/go.xml b/doc/languages-frameworks/go.xml index ab4c9f0f7c885..6f6e7925a1b5f 100644 --- a/doc/languages-frameworks/go.xml +++ b/doc/languages-frameworks/go.xml @@ -3,12 +3,91 @@ xml:id="sec-language-go"> <title>Go</title> - <para> - The function <varname>buildGoPackage</varname> builds standard Go programs. - </para> + <section xml:id="ssec-go-modules"> + <title>Go modules</title> - <example xml:id='ex-buildGoPackage'> - <title>buildGoPackage</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 { + name = "pet-${version}"; + 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> + </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 { name = "deis-${version}"; @@ -29,56 +108,56 @@ deis = buildGoPackage rec { 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> + </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' /> { @@ -101,60 +180,62 @@ deis = buildGoPackage rec { } ] </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: + </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> $ nix-build -A deis.bin </screen> - or build all outputs with: + or build all outputs with: <screen> $ 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> + <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: + <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> + </section> </section> |