# Go

The function `buildGoPackage` builds standard Go programs.

## buildGoPackage

    deis = buildGoPackage rec {
      name = "deis-${version}";
      version = "1.13.0";

      goPackagePath = "github.com/deis/deis";
      subPackages = [ "client" ];

      src = fetchFromGitHub {
        owner = "deis";
        repo = "deis";
        rev = "v${version}";
        sha256 = "1qv9lxqx7m18029lj8cw3k7jngvxs4iciwrypdy0gd2nnghc68sw";
      };

      goDeps = ./deps.json;

      buildFlags = "--tags release";
    }

is an example expression using buildGoPackage, the following arguments are of special significance to the function:

`goPackagePath` specifies the package's canonical Go import path.

`subPackages` limits the builder from building child packages that have not been listed. If `subPackages` is not specified, all child packages will be built.

In this example only `github.com/deis/deis/client` will be built.

`goDeps` is where the Go dependencies of a Go program are listed in a JSON format described below.

`buildFlags` is a list of flags passed to the go build command.

The `goDeps` attribute should point to a JSON file that defines which Go libraries are needed and should be included in `GOPATH` for `buildPhase`.

## deps.json

    [
        {
            "goPackagePath": "gopkg.in/yaml.v2",
            "fetch": {
              "type": "git",
              "url": "https://gopkg.in/yaml.v2",
              "rev": "a83829b6f1293c91addabc89d0571c246397bbf4",
              "sha256": "1m4dsmk90sbi17571h6pld44zxz7jc4lrnl4f27dpd1l8g5xvjhh"
            }
        },
        {
        "include": "../../libs.json",
        "packages": [
                "github.com/docopt/docopt-go",
                "golang.org/x/crypto",
            ]
        }
    ]

`goDeps` is a list of Go dependencies.

`goPackagePath` specifies Go package import path.

`fetch type` that needs to be used to get package source. If `git` is used there should be `url`, `rev` and `sha256` defined next to it.

`include` could be used to reuse `goDeps` between Go programs. There is a common libs set in `<nixpkgs/pkgs/development/go-modules/libs.json>` with pinned versions of many packages that you can reuse.

`packages` enumerates all Go packages that will be imported from included file.

`buildGoPackage` produces where `bin` includes program binaries. You can test build a Go binary as follows:

        $ nix-build -A deis.bin

or build all outputs with:

        $ nix-build -A deis.all

`bin` output will be installed by default with `nix-env -i` or `systemPackages`.

You may use Go packages installed into the active Nix profiles by adding the following to your ~/.bashrc:

    for p in $NIX_PROFILES; do
        GOPATH="$p/share/go:$GOPATH"
    done

To extract dependency information from a Go package in automated way use go2nix. It can produce complete derivation and `goDeps` file for Go programs.