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

 <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 {
  name = "pet-${version}";
  version = "0.3.4";

  src = fetchFromGitHub {
    owner = "knqyf263";
    repo = "pet";
    rev = "v${version}";
    sha256 = "0m2fzpqxk7hrbxsgqplkg7h2p7gv6s1miymv3gvw0cz039skag0s";
  };

  modSha256 = "1879j77k96684wi554rkjxydrj8g3hpp0kvxz03sd8dmwr3lh83j"; <co xml:id='ex-buildGoModule-1' />

  subPackages = [ "." ]; <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>modSha256</varname> is the hash of the output of the
      intermediate fetcher derivation.
     </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>
   </calloutlist>
  </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 {
  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.nix; <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 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>buildFlags</varname> is a list of flags passed to the go build
      command.
     </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>
   <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>
 </section>
</section>