Skip to content

buildGoPackage: updated docs for goPackages after rework #16129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rushmorem merged 1 commit into from
Jun 11, 2016
Merged

buildGoPackage: updated docs for goPackages after rework #16129

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 82 additions & 49 deletions doc/languages-frameworks/go.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,27 +5,29 @@
<title>Go</title>

<para>The function <varname>buildGoPackage</varname> builds
standard Go packages.
standard Go programs.
</para>

<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
<programlisting>
net = buildGoPackage rec {
name = "go.net-${rev}";
goPackagePath = "golang.org/x/net"; <co xml:id='ex-buildGoPackage-1' />
subPackages = [ "ipv4" "ipv6" ]; <co xml:id='ex-buildGoPackage-2' />
rev = "e0403b4e005";
deis = buildGoPackage rec {
name = "deis-${version}";
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 {
inherit rev;
owner = "golang";
repo = "net";
sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
owner = "deis";
repo = "deis";
rev = "v${version}";
sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
};
goPackageAliases = [ "code.google.com/p/go.net" ]; <co xml:id='ex-buildGoPackage-3' />
propagatedBuildInputs = [ goPackages.text ]; <co xml:id='ex-buildGoPackage-4' />
buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-5' />
disabled = isGo13;<co xml:id='ex-buildGoPackage-6' />
};

goDeps = ./deps.json; <co xml:id='ex-buildGoPackage-3' />

buildFlags = "--tags release"; <co xml:id='ex-buildGoPackage-4' />
}
</programlisting>
</example>

Expand All @@ -47,64 +49,94 @@ the following arguments are of special significance to the function:
packages will be built.
</para>
<para>
In this example only <literal>code.google.com/p/go.net/ipv4</literal> and
<literal>code.google.com/p/go.net/ipv6</literal> will be built.
In this example only <literal>github.com/deis/deis/client</literal> will be built.
</para>
</callout>

<callout arearefs='ex-buildGoPackage-3'>
<para>
<varname>goPackageAliases</varname> is a list of alternative import paths
that are valid for this library.
Packages that depend on this library will automatically rename
import paths that match any of the aliases to <literal>goPackagePath</literal>.
</para>
<para>
In this example imports will be renamed from
<literal>code.google.com/p/go.net</literal> to
<literal>golang.org/x/net</literal> in every package that depend on the
<literal>go.net</literal> library.
<varname>goDeps</varname> is where the Go dependencies of a Go program are listed
in a JSON format described below.
</para>
</callout>

<callout arearefs='ex-buildGoPackage-4'>
<para>
<varname>propagatedBuildInputs</varname> is where the dependencies of a Go library are
listed. Only libraries should list <varname>propagatedBuildInputs</varname>. If a standalone
program is being built instead, use <varname>buildInputs</varname>. If a library's tests require
additional dependencies that are not propagated, they should be listed in <varname>buildInputs</varname>.
<varname>buildFlags</varname> is a list of flags passed to the go build command.
</para>
</callout>

<callout arearefs='ex-buildGoPackage-5'>
</calloutlist>

</para>

<para>The <varname>goDeps</varname> attribute should point to a JSON 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.json</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"
}
},
{
"include": "../../libs.json", <co xml:id='ex-goDeps-4' />
"packages": [ <co xml:id='ex-goDeps-5' />
"github.com/docopt/docopt-go",
"golang.org/x/crypto",
]
}
]
</programlisting>
</example>

<para>

<calloutlist>

<callout arearefs='ex-goDeps-1'>
<para>

@rushmorem rushmorem Jun 10, 2016

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we also explain how to build binaries especially now that we can no longer install by the attribute path in all-packages.nix? Say nix-build -A deis.bin for example...

@kamilchm kamilchm Jun 11, 2016

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As it turned out packages can be installed with nix-env -i to have bin in the profile. It all about differences of multiple outputs in nix-build and nix-env. #16103 (comment)

@rushmorem rushmorem Jun 11, 2016

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, @vcunat's explanation helped make things clearer. I don't think this is an issue any more. But the documentation around this is seriously lacking IMHO.

@kamilchm kamilchm Jun 11, 2016

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But is it lacking here or in somewhere between nix-build and multiple outputs? I can mention it here anyway.

@rushmorem rushmorem Jun 11, 2016

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reading nix-build shows that this is in fact documented there. It says "If a derivation has multiple outputs, nix-build will build the default (first) output." How about we make "bin" the default instead (https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/go-modules/generic/default.nix#L198)?

@rushmorem rushmorem Jun 11, 2016 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On second thought the docs say that by convention the default should be dev or out. Thanks again @vcunat!

@kamilchm kamilchm Jun 11, 2016

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So maybe we should leave the decision what needs to be build to developer who want to use nix-build and rely on nix-env default for installation?

@rushmorem rushmorem Jun 11, 2016

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's what I think we should do.

@kamilchm kamilchm Jun 11, 2016

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we remove all .bin attributes from all-packages then?

@rushmorem rushmorem Jun 11, 2016

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes please, I hadn't realised that we added them for other packages besides go2nix.

<varname>buildFlags</varname> is a list of flags passed to the go build command.
<varname>goDeps</varname> is a list of Go dependencies.
</para>
</callout>

<callout arearefs='ex-buildGoPackage-6'>
<callout arearefs='ex-goDeps-2'>
<para>
If <varname>disabled</varname> is <literal>true</literal>,
nix will refuse to build this package.
<varname>goPackagePath</varname> specifies Go package import path.
</para>
</callout>

<callout arearefs='ex-goDeps-3'>
<para>
In this example the package will not be built for go 1.3. The <literal>isGo13</literal>
is an utility function that returns <literal>true</literal> if go used to build the
package has version 1.3.x.
<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>
<callout arearefs='ex-goDeps-4'>
<para>
<varname>include</varname> could be used to reuse <varname>goDeps</varname> between Go programs.
There is a common libs set in <varname>&lt;nixpkgs/pkgs/development/go-modules/libs.json&gt;</varname>
with pinned versions of many packages that you can reuse.
</para>
</callout>

<para>
Reusable Go libraries may be found in the <varname>goPackages</varname> set. You can test
build a Go package as follows:
<callout arearefs='ex-goDeps-5'>
<para>
<varname>packages</varname> enumerates all Go packages that will be imported from included file.
</para>
</callout>

<screen>
$ nix-build -A goPackages.net
</screen>
</calloutlist>

</para>

Expand All @@ -119,6 +151,7 @@ done
</screen>
</para>

<para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/kamilchm/go2nix">go2nix</link>.</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>
</section>