After reading this document, you should be able to produce Debian packages for Go software.

1. General notes

1.1. Team Maintenance

All Go packages are team-maintained in the pkg-go team. This has multiple advantages:

  1. There are no single points of failure, if one maintainer cannot continue maintaining a package, another maintainer can easily help out or take over.

  2. While it is strongly recommended to ask maintainers for permission before touching their package in any significant way, cleanup changes can very easily be applied to all packages.

  3. All packages can share the same technical standards and workflows.

  4. When working within a team anyway, it is much easier to get help on any technical issue.

On the technical side, put pkg-go <pkg-go-maintainers@lists.alioth.debian.org> into the Maintainer field in debian/control and add yourself as Uploader.

1.2. Packaging in git

All Go packages are maintained in git and must be buildable using git-buildpackage.

1.3. Version numbers

Many Go libraries (and also some actual Go programs) don’t have version numbers in the traditional sense, but live in a version control repository of some kind.

In case your upstream does not use version numbers, the Debian package version will look like this:

0.0_git20130606-1

The 0.0 in the beginning is used to allow upstream to adopt version numbers at any point in time and also to make it clear that no traditional version number is used for this package. The second part is the version control system, e.g. git, hg, svn. Afterwards, a date follows in the format YYYYMMDD. The last part after the dash is the Debian version number.

In case you make more than one snapshot per day, you can append a snapshot number after the date, e.g. 0.0_git201306062-1. This should rarely be necessary.

2. Binary-only packages

A binary-only package is a package that contains a program written in Go, but no source code. An example is docker, which is written in Go, but does not offer an API (thus no source code).

2.1. Naming Conventions

The source package should be named like the upstream project, i.e. docker, you do NOT need to call it golang-docker.

Similarly, the resulting binary package(s) should NOT contain the golang- prefix.

2.2. Use dh-golang

Install dh-golang from Debian unstable so that you are using the newest version. The buildds are using the unstable version, too, so this is important.

You will need to change the value of DH_GOPKG to correspond to your program’s upstream package name. This is usually what you would go get when installing it manually. dh-golang needs that information so that it can run go install.

dh-golang sets up a build environment that contains all the libraries that are available in /usr/share/gocode/src, so you need to add Build-Depends to your package. As an example, Debian Code Search depends on golang-pq-dev and others: https://github.com/Debian/dcs/blob/master/debian/control#L5

3. Library (or binary + library) packages

Libraries written in Go are packaged for Debian with the only purpose of building other Go programs for Debian. They are specifically not available for users in their regular development workflow. For that, users should use go get. The rationale behind this decision is:

  • By using go get you are forced to set up the environment variable $GOPATH which you need for other go commands (e.g. go build, go test, etc.).

  • Debian packages install files to system locations, which users cannot modify. That means that users would not be able to upgrade packages with the canonical go get -u <package>. Even worse, when using sudo to forcibly modify the system files, it still would not work since no VCS information is contained in the Debian packages.

3.1. Naming Conventions

For github.com/mstap/godebiancontrol (which contains "go" already), the resulting Debian package name is golang-godebiancontrol-dev.

We use the -dev suffix to keep the namespace clean in case go supports shared libraries in the future, which would then be shipped as golang-godebiancontrol.

In general, you should use the import path for deriving a name, not the actual package name. Ideally, those are the same anyway. In case a package name already exists and you need a more specific one, add just enough qualifiers to make it more specific. These packages (order is relevant!) serve as an example:

Package number Import path Debian package name

1

code.google.com/p/go.net/websocket

golang-websocket-dev

2

github.com/stapelberg/websocket

golang-stapelberg-websocket-dev

3

code.google.com/p/stapelberg/websocket

golang-codegooglecom-stapelberg-websocket-dev

In general, most packages will follow the first, most simple name, sometimes the second example and rarely the third example.

3.2. File locations

All files should be installed into /usr/share/gocode/src/, which corresponds to $GOPATH/src. As an example, for github.com/lib/pq (golang-pq-dev), one of the files is /usr/share/gocode/src/github.com/lib/pq/buf.go.

3.3. Dependencies

Your library package, e.g. golang-pq-dev, needs to have all the other Go libraries it depends on in its Build-Depends and Depends line. The dependencies need to be available at build time to run the tests (if any) and at installation time so that other packages can be built.