NAME

       dh-golang -- debhelper build system class for Go packages

DESCRIPTION

       The dh-golang package provides a build system for debhelper which can be used in the
       following way:

        %:
               dh $@ --buildsystem=golang --with=golang

IMPLEMENTATION

       Here is a brief description of how the golang build system implements each debhelper build
       system stage:

       configure
           Creates a Go workspace (see https://golang.org/doc/code.html#Workspaces) in the build
           directory. Copies the source code into that workspace and symlinks all available
           libraries from /usr/share/gocode/src into the workspace because the go(1) tool
           requires write access to the workspace. See also "DH_GOLANG_INSTALL_EXTRA" and
           "DH_GOLANG_INSTALL_ALL".

       build
           Determines build targets (see also "DH_GOLANG_BUILDPKG" and "DH_GOLANG_EXCLUDES"),
           possibly calls "go generate" (see also "DH_GOLANG_GO_GENERATE"), then calls "go
           install".

       test
           Calls "go test -v" on all build targets.

       install
           Installs binaries and sources from the build directory into the Debian package
           destdir. See also "--no-source" and "--no-binaries".

       clean
           Removes the build directory.

OPTIONS

       dh_auto_install
           --no-source
               By default, all files within the src/ subdirectory of the build directory will be
               copied to /usr/share/gocode/src/ of the Debian package destdir. Specifying the
               "--no-source" option disables this behavior, which is useful if you are packaging
               a program (as opposed to a library).

               Example (in "debian/rules"):

                override_dh_auto_install:
                       dh_auto_install -- --no-source

           --no-binaries
               By default, all files within the bin/ subdirectory of the build directory will be
               copied to /usr/bin/ of the Debian package destdir. Specifying the "--no-binaries"
               option disables this behavior.

               Example (in "debian/rules"):

                override_dh_auto_install:
                       dh_auto_install -- --no-binaries

               Note: instead of using this option (which was added for symmetry with
               "--no-source"), consider not building unwanted binaries in the first place to save
               CPU time on our build daemons; see "DH_GOLANG_EXCLUDES".

ENVIRONMENT VARIABLES

       "DH_GOPKG"
           "DH_GOPKG" (string) contains the Go package name which this Debian package is
           building.

           "DH_GOPKG" is automatically set to the value of the first import path of the
           "XS-Go-Import-Path" "debian/control" field, which can contain several comma-separated
           import paths.

           Example (in "debian/control"):

            XS-Go-Import-Path: github.com/go-mgo/mgo,
                               gopkg.in/mgo.v2,
                               labix.org/v2/mgo,
                               launchpad.net/mgo

           Historical note: before the "XS-Go-Import-Path" field was introduced, we used to set
           "DH_GOPKG" in "debian/rules". When you encounter such a package, please convert it by
           moving the value from "debian/rules" to "debian/control". It is preferable to use the
           "debian/control" field because it is machine-readable and picked up/used by various
           Debian infrastructure tools, whereas "debian/rules" is very hard to parse.

       DH_GOLANG_INSTALL_EXTRA
           "DH_GOLANG_INSTALL_EXTRA" (list of strings, whitespace-separated, default empty)
           enumerates files and directories which are additionally installed into the build
           directory. By default, only files with the following extension are installed: .go, .c,
           .cc, .h, .hh, .proto, .s. Starting with dh-golang 1.31, testdata directory contents
           are installed by default.

           Example (in "debian/rules"):

            export DH_GOLANG_INSTALL_EXTRA := example.toml marshal_test.toml

       DH_GOLANG_INSTALL_ALL
           "DH_GOLANG_INSTALL_ALL" (bool, default false) controls whether all files are installed
           into the build directory. By default, only files with the following extension are
           installed: .go, .c, .cc, .h, .hh, .proto, .s. Starting with dh-golang 1.31, testdata
           directory contents are installed by default.

           Example (in "debian/rules"):

            export DH_GOLANG_INSTALL_ALL := 1

           Note: prefer the "DH_GOLANG_INSTALL_EXTRA" environment variable because it is self-
           documenting and future-proof: when using "DH_GOLANG_INSTALL_ALL", readers of your
           package cannot easily tell which extra files in particular need to be installed, and
           newer upstream versions might result in unexpected extra files.

       DH_GOLANG_BUILDPKG
           "DH_GOLANG_BUILDPKG" (list of strings, whitespace-separated, default
           "${DH_GOPKG}/...") defines the build targets for compiling this Go package. In other
           words, this is what will be passed to "go install".

           The default value matches all Go packages within the source, which is usually desired,
           but you might need to exclude example programs, for which you should use the
           "DH_GOLANG_EXCLUDES" environment variable.

           Example (in "debian/rules"):

            # Install only programs for end users, the also-included Go packages are not
            # yet mature enough to be shipped for other packages to consume (despite what
            # upstream claims).
            export DH_GOLANG_BUILDPKG := github.com/debian/ratt/cmd/...

       DH_GOLANG_EXCLUDES
           "DH_GOLANG_EXCLUDES" (list of Perl regular expressions, whitespace-separated, default
           empty) defines regular expression patterns to exclude from the build targets expanded
           from "DH_GOLANG_BUILDPKG".

           Example (in "debian/rules"):

            # We want to ship only the library packages themselves, not the accompanying
            # example binaries.
            export DH_GOLANG_EXCLUDES := examples/

       DH_GOLANG_GO_GENERATE
           "DH_GOLANG_GO_GENERATE" (bool, default false) controls whether "go generate" is called
           on all build targets (see "DH_GOLANG_BUILDPKG").

           It is convention in the Go community to commit all "go generate" artifacts to version
           control, so re-generating these artifacts is usually not required.

           Depending on what the Go package in question uses "go generate" for, you may want to
           enable "DH_GOLANG_GO_GENERATE":

           •   If the Go package uses "go generate" to generate artifacts purely from inputs
               within its own source (e.g. creating a perfect hash table), there usually is no
               need to re-generate that output. It does not necessarily hurt, either, but some
               "go generate" commands might be poorly tested and break the build.

           •   If the Go package uses "go generate" to (e.g.) bundle a JavaScript library into a
               template file which is then compiled into a Go program, it is advisable to re-
               generate that output so that the Debian version of the JavaScript library is
               picked up, as opposed to the pre-generated version.

           Example (in "debian/rules"):

            export DH_GOLANG_GO_GENERATE := 1

           Note: this option should default to true, but it was introduced after dh-golang was
           already widely used, and nobody made the transition happen yet (i.e. inspect and
           possibly fix any resulting breakages).