ilyakooo0/nixpkgs
1
0
Fork 0
mirror of https://github.com/ilyakooo0/nixpkgs.git synced 2024-12-26 04:43:09 +03:00
Code Issues Projects Releases Wiki Activity

docs/go: Add examples for and explain buildFlags

Browse Source 
Move common attributes treated by both buildGoModule and buildGoPackage
to a separate section, out of the examples' "callouts".

Co-authored-by: zowoq <59103226+zowoq@users.noreply.github.com>
This commit is contained in:
Doron Behar 2020-09-15 11:41:13 +03:00 committed by zowoq
parent 008de9ca3c
commit 5819bca301
1 changed files with 69 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
doc/languages-frameworks/go.xml
View File

@ -38,11 +38,7 @@ pet = buildGoModule rec {
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' />
runVend = true; <co xml:id='ex-buildGoModule-2' />
meta = with lib; {
description = "Simple command-line snippet manager, written in Go";
@ -64,16 +60,6 @@ pet = buildGoModule rec {
</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>
@ -82,12 +68,7 @@ pet = buildGoModule rec {
</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;'
<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>
@ -106,7 +87,6 @@ deis = buildGoPackage rec {
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";
@ -115,11 +95,7 @@ deis = buildGoPackage rec {
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' />
goDeps = ./deps.nix; <co xml:id='ex-buildGoPackage-2' />
}
</programlisting>
</example>
@ -133,28 +109,10 @@ deis = buildGoPackage rec {
</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>
@ -221,4 +179,70 @@ 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>