Differences between revisions 69 and 70
Revision 69 as of 2014-10-14 16:06:59
Size: 17015
Editor: ?ReubenThomas
Comment: Fix call of sbuild-update's argument
Revision 70 as of 2015-02-06 12:10:38
Size: 17622
Editor: josch
Comment: add instructions to build with experimental
Deletions are marked like this. Additions are marked like this.
Line 377: Line 377:

== enabling experimental ==

Go into the schroot by executing

sudo sbuild-shell source:sid-amd64

and run:

echo deb http://ftp.debian.org/debian experimental main >> /etc/apt/sources.list
echo "Package: *\nPin: release a=unstable\nPin-Priority:900" > /etc/apt/preferences.d/unstable.pref
echo "Package: *\nPin: release a=experimental\nPin-Priority:800" > /etc/apt/preferences.d/experimental.pref

then update the schroot:

sudo sbuild-update -udcar sid

To build packages, use the aptitude based resolver:

sbuild --build-dep-resolver=aptitude

Translation(s): none


sbuild is used on the official buildd network to build binary packages for all supported architectures. It can also be used by individuals to prepare packages. Alternatives to sbuild are cowbuilder and pbuilder.

This page is intended as a short guide to sbuild. It documents how to set up sbuild and build packages with it, but intentionally does not document all possible options to keep it short and simple.


To get started so you may build packages for Debian sid, run the following.

   1 sudo apt-get install sbuild
   2 sudo sbuild-update --keygen
   3 sudo sbuild-adduser $LOGNAME
   4  ... *logout* and *re-login*
   5 sudo sbuild-createchroot --make-sbuild-tarball=/var/lib/sbuild/sid-amd64.tar.gz sid `mktemp -d` http://ftp.debian.org/debian

Now for a brief explanation on what these commands do.

The first line installs sbuild onto the system.

The second line generates apt keys used internally by sbuild. (If you get an error about lack of entropy, do something else on the system, like browsing the web or running find /usr or so. Or skip down to creating the chroot, and come back to this step.) This only needs to be done once.

The third line will add your username so that it may use the sbuild command. Additional users may be added by running sudo sbuild-adduser USER1 USER2 ....

sbuild-adduser will prompt you to copy the template sbuild configuration in /usr/share/doc/sbuild/examples/example.sbuildrc to each user's ~/.sbuildrc, to be used as their user sbuild configuration. You can customize sbuild settings here, but you usually won't need to customize anything. This should be done once per user.

The fourth line is to update the active user group set to include sbuild.

The fifth line uses sbuild-createchroot to create a chroot used by sbuild meant for building packages targeting Debian sid main. The chroot is saved as a tarball in /var/lib/sbuild/sid-amd64.tar.gz. The apt repository used is http://ftp.debian.org/debian. This can be changed to use a URL for a local mirror of the Debian archive. You can run this command once per distribution you want, and pass --arch=i386 to create a chroot for a different architecture (the default is your host architecture).


If you're setting up sbuild for personal use, instead of as part of a build server, you might want to use the following options in your ~/.sbuildrc. These can also be set on the command line when running sbuild.

   1 $build_arch_all = 1;
   2 $build_source = 1;
   3 $distribution = 'sid';

The $build_arch_all variable will enable building of architecture independent packages by default. Since official build servers are used to build an existing package for a different architecture (e.g., the uploader builds for i386, uploads arch-i386 and arch-all binary packages, and a build server builds arch-amd64 packages), this is off by default. You can also enable this per build by passing -A to sbuild.

The $build_source variable will enable building of source packages by default. Again, on official build servers, this isn't wanted, but for personal use it's generally useful. You can enable this per build with -s.

The $distribution variable will set the distribution to build for as 'sid'. You can set the distribution per build by passing it to the -d option. Be careful not to use -d just to select a specific chroot (use -c for that, see below), as it will override the distribution set in debian/changelog and may lead you to upload a package to a distribution it was not intended for.


The chroot should be up-to-date before building packages. Use the sbuild-update to perform updates.

First, note the name of the sbuild chroot to be updated. All sbuild chroots built with sbuild-createchroot will have a suffix of '-sbuild' thus to find the names of all sbuild chroots, run the following.

   1 schroot -l | grep sbuild

If you followed the setup instructions above, there should be one chroot named source:sid-$arch-sbuild where $arch is the architecture installed on your machine.

After noting the name of your sbuild chroot, run the following.

   1 sudo sbuild-update -udcar sid-$arch

The arguments '-udcar' will tell sbuild-update to run an apt-get update, dist-upgrade, clean, autoclean, and autoremove in the chroot.

You can also pass --apt-update --apt-distupgrade to the individual sbuild invocation to update the temporary copy of the build chroot, but this won't cause any changes to happen in the persistent copy of the chroot (in the .tar.gz file). So if you are building more than once, you should run sbuild-update instead of relying on this.

Building packages

To build a package from the source directory of a debianized package, simply run the following.

   1 sbuild

Alternatively, you may pass in the '.dsc' file of a package generated by dpkg-buildpackage, git buildpackage, and so forth so that it may be built with sbuild. For example, to build sbuild from its '.dsc' file, do the following.

   1 sbuild sbuild_*.dsc

To build packages available from the apt repositories used in the sbuild chroot, pass in a package to sbuild in the format $package_$version. For example, to build sbuild version 0.63.2-1.1, do the following.

   1 sbuild -d sid sbuild_0.63.2-1.1

Everything needed to build sbuild version 0.63.2-1.1 will be downloaded from the repositories and will be saved in your current directory after building of the packages is finished.

Using lintian

The use of lintian with sbuild can greatly aid with increasing the quality of Debian packages. To use lintian with sbuild, first install lintian.

   1 sudo apt-get install lintian

Next, edit your ~/.sbuildrc configuration file. Open ~/.sbuildrc with your favorite text editor and edit the lines with the following variables.

   1 $run_lintian = 1;
   2 $lintian_opts = ['-i', '-I'];

The $run_lintian variable will enable running of lintian after a successful build with sbuild.

The $lintian_opts variable is an array of options to pass to lintian. Here the options are '-i' which will output information about lintian warnings and errors, and '-I' which will output lintian "info" messages.

Using piuparts

The use of piuparts with sbuild is another feature meant to enhance the quality of Debian packages built with sbuild. To use piuparts, first install piuparts.

   1 sudo apt-get install piuparts

Next, edit your ~/.sbuildrc configuration file. Open ~/.sbuildrc with your favorite text editor and edit the lines with the following variables.

   1 $run_piuparts = 1;
   2 $piuparts_opts = ['-b', '/var/lib/sbuild/sid-amd64.tar.gz'];

The $run_piuparts variable will enable running piuparts after a successful build with sbuild.

The $piuparts_opts variable is an array of options to pass to piuparts. Here the options are the "-b <path/to/tarball>" option in piuparts. This will instruct piuparts to use sbuild chroot '/var/lib/sbuild/sid-amd64.tar.gz' as the chroot used in its testing of packages.

Using autopkgtest

Add this to .sbuildrc:

$external_commands = {
  'post-build-commands' => [
    ['adt-run', '--changes', '%c', '---', 'schroot', 'sid-amd64-sbuild']

Consider configuring schroot with tmpfs or eatmydata, or else running adt-run will slow the build a lot.

Bind mounts

Directories on the local filesystem can be bind mounted and made available in the sbuild chroots. To do this, add an entry in /etc/schroot/sbuild/fstab.

The following example shows how to bind mount the apt archive cache inside an sbuild chroot. This is useful when not using a local mirror of the Debian repository.

   1 sudo sh -c 'echo /var/cache/apt/archives /var/cache/apt/archives none rw,bind 0 0 >>/etc/schroot/sbuild/fstab'

Because of #716703, it might be needed to add  profile=sbuild  to /etc/schroot/chroot.d/sid-<arch>-sbuild-<hash>

Customizations of sbuild chroots

Sometimes it is desirable to further customize your sbuild chroot environment. Typical customizations done are installing more packages inside the chroot, modifying /etc/apt/sources.list, and installing custom scripts to be run inside the chroot.

To modify a chroot, start a session for the chroot with the prefix 'source:'. For example, to modify the sid-$arch-sbuild chroot, start a session for the chroot as follows.

   1 sudo sbuild-shell source:sid-$arch-sbuild

This will start a session inside the sid-$arch-sbuild chroot. Any modifications done inside the chroot will be saved upon exiting. Inside this chroot, you may run apt-get commands to install or remove packages as desired. For example, to install ccache, do the following in the chroot session.

   1 apt-get install ccache

Note that you are already root inside a chroot session. Also, sudo would typically not be installed in the chroot anyway.

Making other modifications such as editing /etc/apt/sources.list or adding scripts inside the chroot is best done from outside the chroot session. In order to do this, leave the current chroot session open and start another terminal session. In the other terminal session, find the path used for the existing chroot session as follows.

   1 schroot --info --all-sessions | grep Path

This should output exactly one line and should specify the path of the chroot session. It should look something like this.

  Path                   /var/lib/schroot/mount/sid-amd64-sbuild-5bad48fe-9823-4454-815f-b869d1d7b22c

Doing an ls on this directory should resemble a standard listing of the '/' directory.

With the above path, the sources.list file will be in the following path.


Open the sources.list file at this path with root privileges using your favorite editor, for example:

   1 sudo -e /var/lib/schroot/mount/sid-amd64-sbuild-5bad48fe-9823-4454-815f-b869d1d7b22c/etc/apt/sources.list

Proceed to edit the sources.list file as you see fit, then save.

To add scripts inside the chroot, simply place the scripts in the following directory.


Be sure to make the scripts executable.

   1 sudo chmod a+x /var/lib/schroot/mount/sid-amd64-sbuild-5bad48fe-9823-4454-815f-b869d1d7b22c/usr/local/bin/*

Other modifications may be done to the chroot, either by running commands available within the chroot session, or by running commands with root privileges via the secondary terminal session. Once you are done making modifications to the chroot, simply exit the session. Inside the chroot session, do the following.

   1 exit

After exiting, your modifications will be saved and made available for every new chroot session created afterwards.

External Commands

sbuild supports running external commands at various stages of the build process. This is useful for cases such as running a script inside the chroot after it has been setup. As an example, to run a script in /usr/local/bin/myscript, edit the $external_commands in the sbuild configuration file ~/.sbuildrc as follows.

   1 $external_commands = {
   2                         'post-build-commands' => [],
   3                         'chroot-setup-commands' => ['/usr/local/bin/myscript'],
   4                         'chroot-cleanup-commands' => [],
   5                         'pre-build-commands' => []
   6                       };

sbuild can also translate certain percent escaped keywords for external commands during certain portions of a build. For example, in post build commands, %SBUILD_CHANGES is changed to the path of the '.changes' file for a successfully built package.

Here is an example of adding a post build command to run /usr/local/bin/postbuildscript with %SBUILD_CHANGES as an argument.

   1 $external_commands = {
   2                         'post-build-commands' => ['/usr/local/bin/postbuildscript', '%SBUILD_CHANGES'],
   3                         'chroot-setup-commands' => ['/usr/local/bin/myscript'],
   4                         'chroot-cleanup-commands' => [],
   5                         'pre-build-commands' => []
   6                       };

See the 'EXTERNAL COMMANDS' section of the sbuild man page for more information on external commands.

Using "ccache" with sbuild

ccache is a compiler wrapper that will cache compilation results (produced object files) from gcc and g++; if you repeatedly compile the same source code (or parts of it), ccache will greatly shorten compilation times by avoiding recompilation of files that it has cached earlier.

This is especially useful during package development, when you might have to rebuild a package with a long compilation phase several times. It is also effective with packages that are frequently updated, because often only a few files actually change during updates to a software.

In order to prepare your sbuild environment for ccache, first perform the following setup in the host environment (i.e., outside the chroot), as user root:

   1 dir=/var/cache/ccache-sbuild
   2 install --group=sbuild --mode=2775 -d $dir
   3 env CCACHE_DIR=$dir ccache --max-size 4G
   4 cat >>/etc/schroot/sbuild/fstab <<END
   5 $dir $dir none rw,bind 0 0
   6 END

This assumes that you trust all members of the sbuild group.

It is perfectly fine to share the cache among chroots, even for different architectures. ccache honours the compiler name, size and timestamp as well as the command line when calculating hash values. At least one of these will differ between builds of the same file for different architectures.

Next place the following script into /var/cache/ccache-sbuild/sbuild-setup:

   1 #!/bin/sh
   2 export CCACHE_DIR=/var/cache/ccache-sbuild
   3 export CCACHE_UMASK=002
   4 export CCACHE_COMPRESS=1
   6 export PATH="/usr/lib/ccache:$PATH"
   8 exec "$@"

and make it executable:

chmod +x /var/cache/ccache-sbuild/sbuild-setup

Then for each chroot ($dist-$arch-sbuild) where you want to enable ccache

  1. Install ccache inside the chroot by running

     schroot -c source:$dist-$arch-sbuild apt-get install ccache
  2. and edit the corresponding configuration file in /etc/schroot/chroot.d/ by appending the line


    (Multiple command-prefix can be joined with commas, in case you already have one configured; see eatmydata below.)

Using eatmydata with sbuild

eatmydata is used when storing data on the system is not that important. This is typically the case during build runs using sbuild. To use eatmydata in sbuild, install the eatmydata package inside the sbuild chroot environment.

To enable first run, as root:

   1 schroot -c source:$dist-$arch-sbuild apt-get install eatmydata

Then edit /etc/schroot/chroot.d/$dist-$arch-sbuild-$suffix to add the line:


If you want to combine this with the ccache instructions from above then use:


Using aufs with sbuild

This simple howto implies you have to :

   1 sudo sbuild-createchroot sid /var/lib/sbuild/sid-amd64 http://ftp.fr.debian.org/debian/

Then add  union-type=aufs  in the created /etc/schroot/chroot.d/sid-amd64-sbuild-xxxx and make sure aufs module is loaded

 modprobe aufs .

Maybe add it to /etc/modules to have it loaded on boot.

Using aufs on tmpfs with sbuild

See also #709774.

Create the executable: /etc/schroot/setup.d/04tmpfs with

   1 #!/bin/sh
   3 set -e
   5 . "$SETUP_DATA_DIR/common-data"
   6 . "$SETUP_DATA_DIR/common-functions"
   7 . "$SETUP_DATA_DIR/common-config"
  10 if [ $STAGE = "setup-start" ]; then
  11   mount -t tmpfs overlay /var/lib/schroot/union/overlay
  12 elif [ $STAGE = "setup-recover" ]; then
  13   mount -t tmpfs overlay /var/lib/schroot/union/overlay
  14 elif [ $STAGE = "setup-stop" ]; then
  15   umount -f /var/lib/schroot/union/overlay
  16 fi

enabling experimental

Go into the schroot by executing

sudo sbuild-shell source:sid-amd64

and run:

echo deb http://ftp.debian.org/debian experimental main >> /etc/apt/sources.list
echo "Package: *\nPin: release a=unstable\nPin-Priority:900" > /etc/apt/preferences.d/unstable.pref
echo "Package: *\nPin: release a=experimental\nPin-Priority:800" > /etc/apt/preferences.d/experimental.pref

then update the schroot:

sudo sbuild-update -udcar sid

To build packages, use the aptitude based resolver:

sbuild --build-dep-resolver=aptitude