---
name: "Debian::Debhelper::Buildsystem::golang"
section: "3pm"
platform: "linux"
package: "dh-golang"
version: "1.63"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Debian::Debhelper::Buildsystem::golang"
---

# Debian::Debhelper::Buildsystem::golang(3pm)

## 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)](/go/1.md) 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).

## SEE ALSO

[**dh**(1)](/dh/1.md), [**dh\_golang**(1p)](/dh_golang/1p.md), [**dh-make-golang**(1)](/dh-make-golang/1.md)