Packaging Go Libraries with dh-make-golang in Debian

This article explains how the dh-make-golang tool automates the creation of Debian packaging files for Go (Golang) libraries. By inspecting upstream Go source code, parsing module definitions, and automatically resolving dependencies into Debian package equivalents, the tool significantly streamlines the workflow for maintaining Go software within the Debian ecosystem.

Source Code Retrieval and Inspection

The packaging workflow begins when a maintainer runs dh-make-golang make <canonical-go-import-path>. The tool clones the target Go repository using Git and inspects its internal configuration. It reads the Go module definition file (go.mod) or scans Go source code files (.go) to detect package metadata, including the project's canonical import path, build tags, and test requirements.

Automated Dependency Mapping

Go projects rely on remote import paths (such as github.com/user/repo), whereas Debian manages dependencies through its native package archive. dh-make-golang bridges this gap through automated translation:

  • Name Translation: It converts canonical Go import paths into standardized Debian source and binary package names. By convention, Go libraries in Debian use the prefix golang-<vendor>-<project>-dev.
  • Archive Querying: The tool queries the Debian package archive and the Debian Go team's metadata repositories to check if upstream dependencies already exist as packaged Debian libraries.
  • Dependency Declaration: Identified dependencies are automatically mapped and inserted into the Build-Depends and Depends fields of the generated Debian control file. If a dependency is missing from Debian, the tool notifies the maintainer so it can be packaged beforehand.

Generation of the debian/ Directory

Creating the packaging skeleton manually is error-prone. dh-make-golang generates a complete, policy-compliant debian/ directory containing all essential files:

  1. debian/control: Contains package metadata, including standard build dependencies, runtime dependencies, maintainer information (typically the Debian Go Packaging Team), Vcs repository URLs, and extended package descriptions extracted from the upstream README or Go documentation.

  2. debian/rules: Produces a minimal Makefile configured to use Debian's debhelper engine alongside the Go build system plugin:

    #!/usr/bin/make -f
%:
 dh $@ --buildsystem=golang --with=golang

    This configuration instructs Debian build daemons to compile, test, and install the library in accordance with Debian Go team standards.

  3. debian/copyright: Scans license files, source headers, and repository roots to generate a machine-readable DEP-5 compliant copyright file, identifying software licenses (such as Apache, MIT, or BSD) and copyright holders.

  4. debian/changelog: Automatically initializes a changelog entry targeting the UNRELEASED distribution, referencing the relevant "Intent to Package" (ITP) bug number filed in Debian’s Bug Tracking System.

Integration with Debian Git Workflows

Beyond flat file generation, dh-make-golang can automatically configure a Git repository using git-buildpackage conventions. It sets up standard branching structures (upstream, master/debian/sid, and pristine-tar), imports upstream tags, and commits the generated debian/ directory on top of the imported source tree. This prepares the Go library for immediate review, building with tools like sbuild or pbuilder, and collaborative maintenance within the Debian Go packaging infrastructure.