nixpkgs-suyu/doc/languages-frameworks/go.xml

<section xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="sec-language-go">

<title>Go</title>

<para>The function <varname>buildGoPackage</varname> builds
standard Go packages.
</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";
  src = fetchFromGitHub {
    inherit rev;
    owner = "golang";
    repo = "net";
    sha256 = "1g7cjzw4g4301a3yqpbk8n1d4s97sfby2aysl275x04g0zh8jxqp";
  };
  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' />
};
</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>code.google.com/p/go.net/ipv4</literal> and
      <literal>code.google.com/p/go.net/ipv6</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.
    </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>.
    </para>
  </callout>

  <callout arearefs='ex-buildGoPackage-5'>
    <para>
      <varname>buildFlags</varname> is a list of flags passed to the go build command.
    </para>
  </callout>

  <callout arearefs='ex-buildGoPackage-6'>
    <para>
      If <varname>disabled</varname> is <literal>true</literal>,
      nix will refuse to build this package.
    </para>
    <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.
    </para>
  </callout>

</calloutlist>

</para>

<para>
Reusable Go libraries may be found in the <varname>goPackages</varname> set. You can test
build a Go package as follows:

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

</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>

  <para>To extract dependency information from a Go package in automated way use <link xlink:href="https://github.com/cstrahan/go2nix">go2nix</link>.</para>
</section>