go-cli-template/docs/PACKAGING.md

Packaging Go Binaries for a Debian OS

This is a primer on Debian packaging for Go. Contained in this project are Makefile targets that are used to create a binary package (.deb archive) of the project.

Tooling

Some key tools should be present on your system before you begin.

sudo apt-get install build-essential devscripts debhelper

This command installs:

• build-essential: A meta-package that pulls in the essential tools for compiling software, such as gcc and make.
• devscripts: A collection of scripts that are incredibly helpful for Debian package maintainers.
• debhelper: A suite of tools that simplifies the packaging process by automating common tasks.

It is assumed your Golang dependencies are already met.

Source vs Binary Packages

A source package typically contains the source code of the upstream project in a .tar.gz file, patches made by the package maintainer, then a Makefile file debian/rules is used by the system to compile the code and create a binary package. These source packages cannot be directly installed, but they are highly portable and sometimes required for security auditing.

You are probably more familiar with binary packages. These are pre-compiled packages that are ready to install. They typically consist of the pre-compiled binary, configuration files, man pages, and other necessary data files. The contents are organized into a specific directory structure that a package manager (.e.g. apt) will place on to your file system.

Binary packages need to be compiled for a specific processor architecture (e.g. x86_64 ARM64). Most times these are built for a specific operating system and version too. A benefit to this process is that dev tools do not need to be installed for a user to make use of the package.

This project focuses on building a binary package.

Package Files and Structure

When building a Debian package you must create a debian/ directory which in a typical build process will contain a number of essential files.

• debian/control: Contains essential metadata about the source package and the binary package(s) it will create. This includes the package name, version, dependencies, maintainer information, and a description of the software
• debian/rules: This is an executable Makefile that automates the building of the package. It has targets for compiling the software (build), installing it into a temporary directory (install), and creating the final .deb archive(binary). Modern rules files are often very simple, relying on debhelper to do the heavy lifting
• debian/changelog: This file documents the changes made to the Debian package, not the upstream software. It follows a strict format and is used by the build tools to determine the package version.
• debian/copyright: This file specifies the copyright and license of the software. It's a legal requirement and should accurately reflect the licensing terms of the upstream source code and any modifications made for the Debian package.
• debian/compat: This file specifies the debhelper compatibility level, which ensures that the build process is consistent even as debhelper evolves.
• debian/source/format: This file indicates the source package format (e.g., 3.0 (quilt))

A binary package for can be constructed for Go with as little as a control and changelog file. Since this primer is focused on a minimal packaging process for your own golang project, we will focus on the control file and the changelog.

Control File

The debian/control file

• control

Changelog

The change log is not a change log of the upstream, it is a changelog of the Debian package. This file has a specific format that needs to be adhered to, or the build will fail.

A debian/changelog file is a plain text file with a series of entries, where the newest entry is always at the very top. Each entry has a precise format:

package-name (version) distribution(s); urgency=level

    * Change details for the first change in this version.
    (This can wrap to multiple lines if indented).

    * Change details for the second change. This could be a bug fix.
    (Closes: #bug-number)

    -- Maintainer Name <maintainer@example.com>  Day, dd Mon yyyy hh:mm:ss +zzzz

The devscripts package installed earlier can assist in automating the change log changes, and ensure that they correctly formatted.

Debian Versioning Scheme

[epoch:]upstream_version[-debian_revision]

• epoch: small, rarely used integer that helps correct mistakes in past versioning by ensuring a new version is seen as "later" than an old one
• upstream_version: The main version number from the original software developer, which can contain alphanumeric characters and symbols like periods, hyphens, and colons
• debian_revision is appended by the package maintainer to signify changes to the packaging itself, such as updates to dependencies or build scripts, without any change to the upstream software

When assessing versions dpkg's algorithm evaluates the string from left to right, with special rules for characters like the tilde (~), which indicates a pre-release version and sorts before a final release of the same number.

A Manual Packaging Process Example

Let's assume we have a foo v0.1.0 program that we would like to offer as a debian package.

go build -o ./build/foo .

Create a the debian package structure.

mkdir -p ./dist/foo_0.1.0-1/DEBIAN
mkdir -p ./dist/foo_0.1.0-1/usr/local/bin

Copy the binary to the usr/local/bin/ directory under our package namespace and ensure it's executable.

cp ./build/foo ./dist/foo_0.1.0-1/usr/local/bin/foo
chmod +x ./dist/foo_0.1.0-1/usr/local/bin/foo

Now create a control file under the DEBIAN/ directory

touch ./dist/foo_0.1.0-1/DEBIAN/control