nixpkgs/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 programs.
</para>

<example xml:id='ex-buildGoPackage'><title>buildGoPackage</title>
<programlisting>
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 {
    owner = "deis";
    repo = "deis";
    rev = "v${version}";
    sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
  };

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

  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
      in a JSON format 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 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>
      <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>

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

  <callout arearefs='ex-goDeps-5'>
    <para>
      <varname>packages</varname> enumerates all Go packages that will be imported from included file.
    </para>
  </callout>

</calloutlist>

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

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

<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/kamilchm/go2nix">go2nix</link>.
  It can produce complete derivation and <varname>goDeps</varname> file for Go programs.</para>
</section>