Debian sbuild: Building Packages in Clean Chroots

This article provides an overview of sbuild, the standard tool used by Debian maintainers to compile software packages in isolated, pristine environments. It covers the fundamentals of what sbuild does, why building in a clean chroot is critical for Debian packaging, how to install and configure the necessary tools, and the step-by-step workflow for creating chroots and building binary packages safely and reliably.

What is sbuild?

sbuild (short for "Source Builder") is a tool designed to build Debian binary packages directly from Debian source packages. It is the core engine powering Debian's official automated build daemons (buildd).

Instead of building software directly on your host operating system, sbuild creates an isolated chroot (change root) environment containing only an absolute minimal Debian installation. It automatically installs the specific packages listed in your package's Build-Depends field, compiles the software, produces the resulting .deb files, and then tears down or resets the environment.

Why Use sbuild for Debian Packaging?

Building packages in your host system risks missing dependencies: if a required library is already installed on your workstation, the build succeeds locally, but fails on other systems because the dependency was omitted from the debian/control file.

Using sbuild guarantees:

  • Dependency Accuracy: Catches missing or incomplete Build-Depends.
  • Host Protection: Prevents experimental build steps or malicious scripts from affecting your host system.
  • Reproducibility: Ensures consistent build environments across multiple machines and Debian architectures.
  • Multi-Distribution Support: Allows you to build packages targeting Debian Stable, Testing, or Unstable on the same machine without reinstallation.

Setting Up sbuild

To set up an sbuild workflow on Debian, you need sbuild, along with schroot (for managing chroot environments) and debootstrap (for creating minimal Debian systems).

1. Installation

Run the following command as root or with sudo:

sudo apt update
sudo apt install sbuild schroot debootstrap uidmap

2. User Configuration

Add your user to the sbuild group to grant permission to manage builds:

sudo sbuild-adduser $USER

After running this command, log out and log back in, or run newgrp sbuild to apply the group changes to your current terminal session.

Creating a Build Chroot

Before compiling packages, generate a clean chroot. The sbuild-createchroot command sets up the base system and registers it with schroot.

To create a standard build chroot for Debian Unstable (sid):

sudo sbuild-createchroot \
    --include=eatmydata \
    unstable \
    /srv/chroot/unstable-amd64-sbuild \
    http://deb.debian.org/debian
  • --include=eatmydata: Speeds up builds by disabling fsync calls safely within the disposable chroot.
  • unstable: The Debian suite target.
  • /srv/chroot/unstable-amd64-sbuild: The destination path for the chroot files.
  • http://deb.debian.org/debian: The mirror used to download the packages.

Building Packages with sbuild

Once the chroot is prepared, you can build packages from either an unpacked source directory or a .dsc (Debian Source Control) file.

Building from a .dsc File

Run sbuild and specify the target distribution:

sbuild -d unstable example-package_1.0-1.dsc

Building from a Git/Source Directory

Navigate to the root of the unpacked source package (the directory containing debian/) and execute:

sbuild -d unstable

Common Build Options

  • -s / --source: Generates source packages in addition to binary packages.
  • --force-orig-source: Ensures the original upstream source archive (.orig.tar.gz) is included in the build output.
  • -A: Builds all architecture-independent packages (Architecture: all).

The resulting .deb, .dsc, .changes, and .build log files will be placed in the parent directory of your source tree or current working directory.

Maintaining the Chroot

Because Debian Unstable and Testing receive regular updates, your build chroots must be kept current to reflect modern dependency trees.

Update a chroot using sbuild-update:

sbuild-update -udcar unstable

The flags perform the following steps:

  • -u: Updates the package lists (apt update).
  • -d: Performs a distribution upgrade (apt dist-upgrade).
  • -c: Cleans the local cache (apt clean).
  • -a: Automatically removes unused dependencies (apt autoremove).
  • -r: Checks and cleans up any stale sessions.