Provided by: dh-golang_1.59_all 
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 by adding
dh-sequence-golang to the package build dependencies, and passing the following options to
dh:
%:
dh $@ --builddirectory=_build --buildsystem=golang
Starting with debhelper 13.4 (a versioned build dependency is currently required), the
build system is automatically detected, and the following is enough:
%:
dh $@ --builddirectory=_build
Starting with debhelper compatibility level 14, the build directory defaults to _build,
and the following is enough:
%:
dh $@
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
"DH_GOPKG" is set by dh-golang, and as a consequence it is not present in the
"debian/rules" environment. If you need to use the Go package name in the
"debian/rules" file, you must define it yourself.
Example (in "debian/rules"):
export DH_GOPKG := github.com/go-mgo/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, .cpp, .h, .hh, hpp, .proto, .s. Starting with dh-golang 1.31, testdata directory
contents are installed by default. Starting with dh-golang 1.39, go.mod and go.sum
are installed by default to support Go 1.11 modules.
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, .cpp, .h, .hh, .hpp, .proto, .s. Starting with dh-golang
1.31, testdata directory contents are installed by default. Starting with dh-golang
1.39, go.mod and go.sum are installed by default to support Go 1.11 modules.
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".
Please note that with DH_COMPAT level inferior or equal to 11, the default is to only
exclude pattern from the build target. (see "DH_GOLANG_EXCLUDES_ALL" below)
Example (in "debian/rules"):
# We want to build only the library packages themselves, not the accompanying
# example binaries.
export DH_GOLANG_EXCLUDES := examples/
DH_GOLANG_EXCLUDES_ALL
"DH_GOLANG_EXCLUDES_ALL" (boolean, default to true starting from DH_COMPAT level 12)
makes "DH_GOLANG_EXCLUDE" excludes files not only during the building process but also
for install. This is useful, if, for instance, examples are installed with
"dh_installexamples". If you only want to exclude files from the building process but
keep them in the source, set this to false. Example (in "debian/rules"):
# We want to ship only the library packages themselves in the go source, not
# the accompanying example binaries.
export DH_GOLANG_EXCLUDES := examples/
export DH_GOLANG_EXCLUDES_ALL := 1
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).