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.
222 lines
9.3 KiB
Markdown
222 lines
9.3 KiB
Markdown
# 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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`
|
|
|
|
```bash
|
|
which foo
|
|
|
|
/usr/local/bin/foo
|
|
```
|
|
|
|
We can see which version of the package is installed
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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.
|