Debian...golang(3pm)

📦
version 1.67 · 7 versions
, in ubuntu stonking

🌸 NAME 🌸

Hiii bestie, you're reading the Debian...golang(3pm) page from the User Contributed Perl Documentation, and it's all about dh-golang — the debhelper build system class for Go packages. Slay. 💖

🛠️ DESCRIPTION 🛠️

Okay so, the dh-golang package provides a build system for debhelper. You use it 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 can be automatically detected, and if there is no other upstream build system with a higher dh priority, then the following might be enough — but it should be verified before removal:

%:
        dh $@ --builddirectory=_build

Starting with debhelper compatibility level 14, the build directory defaults to _build, and the following might be enough, with the same caveat about the buildsystem as with the previous example:

%:
        dh $@
Note: Depending on the upstream project and their objectives, removing the explicit --buildsystem=golang option might be error prone if it is likely that new upstream versions could introduce additional build systems with a higher dh priority. 💀

🧚 IMPLEMENTATION 🧚

Here's the tea on 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 --no-source disables this behavior, which is useful if you are packaging a program (as opposed to a library).
  • --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 --no-binaries disables this behavior.

Example for --no-source (in debian/rules):

override_dh_auto_install:
        dh_auto_install -- --no-source

Example for --no-binaries (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. Starting with dh-golang 1.64, go.mod and go.sum from subdirectories are installed by default as well (multiple modules in one repository).

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. Starting with dh-golang 1.64, go.mod and go.sum from subdirectories are installed by default as well (multiple modules in one repository).

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). 😭

👀 SEE ALSO 👀

🫶 fin, bestie. Source/version: perl v5.42.3; date: 2026-09-02; and yes, it's still the Debian...golang(3pm) page. Byeee 💖✨
📦 where this page comes from