doc/go: convert to markdown
This commit is contained in:
Jörg Thalheim
parent
850a73b236
commit
80b395015b
3 changed files with 141 additions and 249 deletions
140
doc/languages-frameworks/go.section.md
Normal file
140
doc/languages-frameworks/go.section.md
Normal file
|
|
@ -0,0 +1,140 @@
|
|||
# Go {#sec-language-go}
|
||||
|
||||
## Go modules {#ssec-language-go}
|
||||
|
||||
The function `buildGoModule` builds Go programs managed with Go modules. It builds a [Go Modules](https://github.com/golang/go/wiki/Modules) 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.
|
||||
|
||||
### Example for `buildGoModule` {#ex-buildGoModule}
|
||||
|
||||
In the following is an example expression using `buildGoModule`, the following arguments are of special significance to the function:
|
||||
|
||||
- `vendorSha256`: is the hash of the output of the intermediate fetcher derivation. `vendorSha256` can also take `null` 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;`
|
||||
- `runVend`: 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.
|
||||
|
||||
```nix
|
||||
pet = buildGoModule rec {
|
||||
pname = "pet";
|
||||
version = "0.3.4";
|
||||
|
||||
src = fetchFromGitHub {
|
||||
owner = "knqyf263";
|
||||
repo = "pet";
|
||||
rev = "v${version}";
|
||||
sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
|
||||
};
|
||||
|
||||
vendorSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j";
|
||||
|
||||
runVend = true;
|
||||
|
||||
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;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## `buildGoPackage` (legacy) {#ssec-go-legacy}
|
||||
|
||||
The function `buildGoPackage` builds legacy Go programs, not supporting Go modules.
|
||||
|
||||
### Example for `buildGoPackage`
|
||||
|
||||
In the following is an example expression using buildGoPackage, the following arguments are of special significance to the function:
|
||||
|
||||
- `goPackagePath` specifies the package's canonical Go import path.
|
||||
- `goDeps` 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 `deps.nix` file for readability. The dependency data structure is described below.
|
||||
|
||||
```nix
|
||||
deis = buildGoPackage rec {
|
||||
pname = "deis";
|
||||
version = "1.13.0";
|
||||
|
||||
goPackagePath = "github.com/deis/deis";
|
||||
|
||||
src = fetchFromGitHub {
|
||||
owner = "deis";
|
||||
repo = "deis";
|
||||
rev = "v${version}";
|
||||
sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
|
||||
};
|
||||
|
||||
goDeps = ./deps.nix;
|
||||
}
|
||||
```
|
||||
|
||||
The `goDeps` attribute can be imported from a separate `nix` file that defines which Go libraries are needed and should be included in `GOPATH` for `buildPhase`:
|
||||
|
||||
```nix
|
||||
# deps.nix
|
||||
[ # goDeps is a list of Go dependencies.
|
||||
{
|
||||
# goPackagePath specifies Go package import path.
|
||||
goPackagePath = "gopkg.in/yaml.v2";
|
||||
fetch = {
|
||||
# `fetch type` that needs to be used to get package source.
|
||||
# If `git` is used there should be `url`, `rev` and `sha256` defined next to it.
|
||||
type = "git";
|
||||
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";
|
||||
};
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
To extract dependency information from a Go package in automated way use [go2nix](https://github.com/kamilchm/go2nix). It can produce complete derivation and `goDeps` file for Go programs.
|
||||
|
||||
You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc:
|
||||
|
||||
```bash
|
||||
for p in $NIX_PROFILES; do
|
||||
GOPATH="$p/share/go:$GOPATH"
|
||||
done
|
||||
```
|
||||
|
||||
## Attributes used by the builders {#ssec-go-common-attributes}
|
||||
|
||||
Both `buildGoModule` and `buildGoPackage` can be tweaked to behave slightly differently, if the following attributes are used:
|
||||
|
||||
### `buildFlagsArray` and `buildFlags`: {#ex-goBuildFlags-noarray}
|
||||
|
||||
These attributes set build flags supported by `go build`. We recommend using `buildFlagsArray`. The most common use case of these attributes is to make the resulting executable aware of its own version. For example:
|
||||
|
||||
```nix
|
||||
buildFlagsArray = [
|
||||
# Note: single quotes are not needed.
|
||||
"-ldflags=-X main.Version=${version} -X main.Commit=${version}"
|
||||
];
|
||||
```
|
||||
|
||||
```nix
|
||||
buildFlagsArray = ''
|
||||
-ldflags=
|
||||
-X main.Version=${version}
|
||||
-X main.Commit=${version}
|
||||
'';
|
||||
```
|
||||
|
||||
### `deleteVendor` {#var-go-deleteVendor}
|
||||
|
||||
Removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
|
||||
|
||||
### `subPackages` {#var-go-subPackages}
|
||||
|
||||
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.
|
||||
|
|
@ -1,248 +0,0 @@
|
|||
<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' />
|
||||
|
||||
runVend = true; <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>vendorSha256</varname> is the hash of the output of the intermediate fetcher derivation.
|
||||
</para>
|
||||
</callout>
|
||||
<callout arearefs='ex-buildGoModule-2'>
|
||||
<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' />
|
||||
|
||||
src = fetchFromGitHub {
|
||||
owner = "deis";
|
||||
repo = "deis";
|
||||
rev = "v${version}";
|
||||
sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
|
||||
};
|
||||
|
||||
goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-2' />
|
||||
}
|
||||
</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>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>
|
||||
</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 xml:id="ssec-go-common-attributes">
|
||||
<title>Attributes used by the builders</title>
|
||||
|
||||
<para>
|
||||
Both <link xlink:href="#ssec-go-modules"><varname>buildGoModule</varname></link> and <link xlink:href="#ssec-go-modules"><varname>buildGoPackage</varname></link> can be tweaked to behave slightly differently, if the following attributes are used:
|
||||
</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry xml:id="var-go-buildFlagsArray">
|
||||
<term>
|
||||
<varname>buildFlagsArray</varname> and <varname>buildFlags</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
These attributes set build flags supported by <varname>go build</varname>. We recommend using <varname>buildFlagsArray</varname>. The most common use case of these attributes is to make the resulting executable aware of its own version. For example:
|
||||
</para>
|
||||
<example xml:id='ex-goBuildFlags-nospaces'>
|
||||
<title>buildFlagsArray</title>
|
||||
<programlisting>
|
||||
buildFlagsArray = [
|
||||
"-ldflags=-X main.Version=${version} -X main.Commit=${version}" <co xml:id='ex-goBuildFlags-1' />
|
||||
];
|
||||
</programlisting>
|
||||
</example>
|
||||
<calloutlist>
|
||||
<callout arearefs='ex-goBuildFlags-1'>
|
||||
<para>
|
||||
Note: single quotes are not needed.
|
||||
</para>
|
||||
</callout>
|
||||
</calloutlist>
|
||||
<example xml:id='ex-goBuildFlags-noarray'>
|
||||
<title>buildFlagsArray</title>
|
||||
<programlisting>
|
||||
buildFlagsArray = ''
|
||||
-ldflags=
|
||||
-X main.Version=${version}
|
||||
-X main.Commit=${version}
|
||||
'';
|
||||
</programlisting>
|
||||
</example>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry xml:id="var-go-deleteVendor">
|
||||
<term>
|
||||
<varname>deleteVendor</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
Removes the pre-existing vendor directory. This should only be used if the dependencies included in the vendor folder are broken or incomplete.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry xml:id="var-go-subPackages">
|
||||
<term>
|
||||
<varname>subPackages</varname>
|
||||
</term>
|
||||
<listitem>
|
||||
<para>
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</section>
|
||||
</section>
|
||||
|
|
@ -13,7 +13,7 @@
|
|||
<xi:include href="crystal.section.xml" />
|
||||
<xi:include href="emscripten.section.xml" />
|
||||
<xi:include href="gnome.xml" />
|
||||
<xi:include href="go.xml" />
|
||||
<xi:include href="go.section.xml" />
|
||||
<xi:include href="haskell.section.xml" />
|
||||
<xi:include href="idris.section.xml" />
|
||||
<xi:include href="ios.section.xml" />
|
||||
|
|
|
|||
Loading…
Reference in a new issue