androiddrew
/
go-cli-template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
go-cli-template/docs/PACKAGING.md

9.3 KiB
Raw Permalink Blame History

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 defines a package's metadata and build-time parameters. Refer to https://www.debian.org/doc/debian-policy/ch-controlfields.html for indepth descriptions of all the available fields. The most minimal file can contain

Package: YOUR_PACKAGE_NAME
Version: YOUR_DEBIAN_PACKAGE_VERSION
Architecture: YOUR_TARGET_PROCESSOR_ARCHITECTURE
Maintainer: YOUR_EMAIL(Ex: Your Name <youremail@example.com>)
Description: YOUR_PACAKGE_DESCRIPTION

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 has the dch(debchange) tool that 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

Create a control file under the DEBIAN/ directory

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

And using a text editor add:

Package: foo
Version: 0.1.0-1
Architecture: amd64
Maintainer: Your Name <youremail@example.com>
Description: foo - A Go Application

Now create a changelog file under the DEBIAN/ directory.

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

We will use the debchange tool dch to create the first entry in our file. Use man dch to learn more about all the options available to you for editing these entries.

dch --changelog ./dist/foo_0.1.0-1/DEBIAN/changelog --create

Since we did not set envvars for things like our package or maintainer email you will see warnings. Press enter to continue and you will drop into an text editor with a basic template.

output:

PACKAGE (VERSION) UNRELEASED; urgency=medium

  * Initial release. (Closes: #XXXXXX)

 -- toor <toor@toor-runcible>  Thu, 26 Jun 2025 14:28:27 -0400

Change the contents of this entry as needed and save.

foo (0.1.0-1) unstable; urgency=low

  * Initial release.

 -- me <me@example.com>  Thu, 26 Jun 2025 14:28:27 -0400

Now we can build the package with dpkg-deb. Again see man dpkg-deb for more information.

cd ./dist
dpkg-deb --build foo_0.1.0-1/

pkg-deb: building package 'foo' in 'foo_0.1.0-1.deb'.

You should now have successfully built a foo_0.1.0-1.deb in your ./dist/ directory.

You can view the contents of this pacakge

dpkg-deb --contents ./foo_0.1.0-1.deb`

drwxrwxr-x toor/toor         0 2025-06-22 15:44 ./
drwxrwxr-x toor/toor         0 2025-06-22 15:44 ./usr/
drwxrwxr-x toor/toor         0 2025-06-22 15:44 ./usr/local/
drwxrwxr-x toor/toor         0 2025-06-22 15:44 ./usr/local/bin/
-rwxrwxr-x toor/toor   3433713 2025-06-22 15:44 ./usr/local/bin/foo

You can test the installation of this new package

sudo dpkg -i ./foo_0.1.0-1.deb

Selecting previously unselected package dirp.
(Reading database ... 217265 files and directories currently installed.)
Preparing to unpack foo_0.1.0-1.deb ...
Unpacking foo (0.1.0-1) ...
Setting up foo (0.1.0-1)

We can check that a the binary is now in our /usr/local/bin

which foo

/usr/local/bin/foo

We can see which version of the package is installed

dpkg -l foo

Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name           Version      Architecture Description
+++-==============-============-============-=================================
ii  foo            0.1.0-1      amd64        foo - A Go application

And we can remove it.

sudo dpkg -r foo

(Reading database ... 217268 files and directories currently installed.)
Removing dirp (0.1.0-1) ...
dpkg: warning: while removing dirp, directory '/usr/local/bin' not empty so not removed

We can disregard the warning because the package manager is doing what its supposed to. It removed the /usr/local/bin/foo and attempts to clean up all directories it may have created in the process. Once it finds existing files in the directory structure it was avoid deleting them.