Provided by: sbuild_0.85.10ubuntu1_all 
NAME
sbuild - build debian packages from source
SYNOPSIS
sbuild [-h|--help | -V|--version] [-v|--verbose | -q|--quiet] [-D|--debug] [-A|--arch-all]
[--archive=archive] [-d|--dist=distribution] [-c|--chroot=chroot]
[--chroot-mode=schroot|sudo|autopkgtest|unshare] [--arch=architecture] [--arch-any | --no-arch-any]
[--build=architecture] [--host=architecture] [--profiles=profile[,...]] [-s|--source]
[--force-orig-source] [--make-binNMU=changelog-entry] [--binNMU=NMU-version] [--append-to-version=string]
[--binNMU-timestamp=timestamp] [--binNMU-changelog=changelog] [--build-dir=directory]
[--add-depends=dependency] [--add-conflicts=dependency] [--add-depends-arch=dependency]
[--add-conflicts-arch=dependency] [--add-depends-indep=dependency] [--add-conflicts-indep=dependency]
[-m|--maintainer=maintainer] [-e|--uploader=uploader] [-k|--keyid=key-id] [--source-only-changes]
[--no-source-only-changes] [-j|--jobs=n] [--enable-network] [--no-enable-network] [--debbuildopt=option]
[--debbuildopts=options] [--dpkg-source-opt=options] [--dpkg-source-opts=options]
[--dpkg-file-suffix=suffix] [-p|--purge=purge-mode] [--purge-build=purge-mode] [--purge-deps=purge-mode]
[--purge-session=purge-mode] [-b|--batch] [-n|--nolog] [--clean-source] [--no-clean-source]
[--run-lintian] [--no-run-lintian] [--lintian-opt=options] [--lintian-opts=options] [--run-piuparts]
[--no-run-piuparts] [--piuparts-opt=options] [--piuparts-opts=options] [--piuparts-root-arg=options]
[--piuparts-root-args=options] [--run-autopkgtest] [--no-run-autopkgtest] [--autopkgtest-opt=options]
[--autopkgtest-opts=options] [--autopkgtest-root-arg=options] [--autopkgtest-root-args=options]
[--pre-build-commands=string] [--chroot-setup-commands=string] [--chroot-update-failed-commands=string]
[--build-deps-failed-commands=string] [--starting-build-commands=string]
[--finished-build-commands=string] [--build-failed-commands=string] [--chroot-cleanup-commands=string]
[--post-build-commands=string] [--post-build-failed-commands=string] [--anything-failed-commands=string]
[--log-external-command-output] [--log-external-command-error] [--setup-hook=hook-script]
[--build-dep-resolver=resolver] [--resolve-alternatives|--no-resolve-alternatives]
[--extra-package=package.deb|directory] [--extra-repository=spec] [--extra-repository-key=file.asc]
[--build-path=string] [--dsc-dir=string] [--autopkgtest-virt-server=schroot|lxc|chroot|qemu|ssh]
[--autopkgtest-virt-server-opt=string] [--autopkgtest-virt-server-opts=options] [--purge-extra-packages]
[--bd-uninstallable-explainer=dose3|apt|none] [PACKAGE[.dsc]]
DESCRIPTION
sbuild rebuilds Debian binary packages from the corresponding Debian source, installing any missing
source dependencies. The build takes place in a dedicated clean build environment, rather than on the
host system. For an overview of the supported chroot backends see the section CHROOT MODES.
sbuild can fetch the Debian source over a network, or it can use locally available sources.
sbuild is given a packages to process as the argument PACKAGE[.dsc]. This argument is in the form of
either a debianized package source directory, a source package name along with a version in the form
package_version, a source package name, or a .dsc file. If no arguments are given, the current working
directory is passed as an argument.
For arguments given as source directories, dpkg-source is first run to produce a source .dsc file. Then,
the package is built using the .dsc produced. For arguments in the form package_version or package, apt
is used to download the source package. For arguments given as a .dsc file, sbuild builds the source
packages directly. For .dsc files in remote locations, the source packages are downloaded first, then
built.
It is also possible to run external commands with sbuild. See the section EXTERNAL COMMANDS for more on
this.
sbuild mails the build logs to a user. It is configured by the configuration files
/etc/sbuild/sbuild.conf and ~/.sbuildrc. An example sbuildrc is available in
/usr/share/doc/sbuild/examples/example.sbuildrc. A custom path to a configuration file can also be
specified through setting the SBUILD_CONFIG environment variable to the path of an additional
configuration file.
You can build either using a local package with its .dsc file or a remote one by specifying an explicit
dpkg version.
OPTIONS
Options set on the command line overwrite settings made in the configuration file.
-h, --help
Display this manual.
-V, --version
Print version information.
--add-depends=dependency
--add-conflicts=dependency
--add-depends-arch=dependency
--add-conflicts-arch=dependency
--add-depends-indep=dependency
--add-conflicts-indep=dependency
These options add a build dependencies to the source package being built, in addition to the build
dependency information specified in debian/control. These dependencies will be concatenated
directly to the Build-Depends, Build-Conflicts, Build-Depends-Arch, Build-Conflicts-Arch,
Build-Depends-Indep and Build-Conflicts-Indep dependencies, respectively. The options may be used
any number of times to add multiple dependencies. The format is identical to the format used in
debian/control. These command line options append to the MANUAL_DEPENDS, MANUAL_CONFLICTS,
MANUAL_DEPENDS_ARCH, MANUAL_CONFLICTS_ARCH, MANUAL_DEPENDS_INDEP and MANUAL_CONFLICTS_INDEP
configuration variables, respectively. See sbuild.conf(5) for more information.
--arch=architecture
Build using the architecture specified. A chroot named $distribution-$arch-sbuild or
$distribution-arch is searched for, in that order of preference. The chroot must be installed and
configured appropriately to build as that architecture, e.g. using personality=linux32 to build
i386 packages on an amd64 system. Note that this option is equivalent to "--host=architecture
--build=architecture". This command line option sets the HOST_ARCH and BUILD_ARCH configuration
variables. See sbuild.conf(5) for more information.
--host=architecture
Build using the host architecture specified. If $host and $build don't match, a chroot named
$distribution-$build-$host-sbuild or $distribution-$build-$host is searched for, falling back to
$distribution-$build-sbuild or $distribution-$build, in that order of preference. This option is
only useful for cross-building when used together with --build. This command line option sets the
HOST_ARCH configuration variable. See sbuild.conf(5) for more information.
--build=architecture
Build using the build architecture specified. This option is only useful for cross-building when
used together with --host. If --build is not specified, the default system architecture is
assumed. This command line option sets the BUILD_ARCH configuration variable. See sbuild.conf(5)
for more information.
-A, --arch-all
Also build Architecture: all packages. This is the default behaviour for native builds. This
option is the opposite of --no-arch-all. See the section BUILD ARTIFACTS for more information.
This command line option sets the BUILD_ARCH_ALL configuration variable. See sbuild.conf(5) for
more information.
--no-arch-all
Do not build Architecture: all packages. This is the default behaviour for cross builds. This
option is the opposite of --arch-all. See the section BUILD ARTIFACTS for more information. This
command line option sets the BUILD_ARCH_ALL configuration variable. See sbuild.conf(5) for more
information.
--arch-any
Build Architecture: any packages. This is the default behavior. This option is the opposite of
--no-arch-any. See the section BUILD ARTIFACTS for more information. This command line option
sets the BUILD_ARCH_ANY configuration variable. See sbuild.conf(5) for more information.
--no-arch-any
Do not build Architecture: any packages. This option is the opposite of --arch-any and only useful
when used together with --arch-all or --source. See the section BUILD ARTIFACTS for more
information. This command line option sets the BUILD_ARCH_ANY configuration variable. See
sbuild.conf(5) for more information.
-b, --batch
Operate in batchmode, i.e. write a build-progress file during execution and files on shutdown to
facilitate a clean restart. This command line option sets the BATCH_MODE configuration variable.
See sbuild.conf(5) for more information.
-c, --chroot=chroot
Specifies the chroot to use. The effect of this option depends on the selected chroot mode. With
the schroot chroot mode, this option specifies the schroot name or alias to use. If not specified,
the default is the first of schroot name or alias that matches $distribution-$arch-sbuild,
$distribution-sbuild, $distribution-$arch or $distribution that exists. With the sudo chroot
mode, this option specifies the chroot directory to use. The directory is either expected in
/etc/sbuild/chroot (in buildd sbuild mode) or in the build directory (see --build-dir), prefixed
with "chroot-" (in user sbuild mode, the default). If not specified, the default is to search for
a directory in the respective locations named in the same way as for the schroot mode. With the
unshare chroot mode, if this option is a path, then it specifies the location of the chroot
tarball directly. Otherwise, a tarball with equal basename from ~/.cache/sbuild will be used. If
not specified, the default is to search for a tarball named in the same way as for the schroot
mode under ~/.cache/sbuild. With the autopkgtest chroot mode this option has no effect. The
--autopkgtest-virt-server-opts are used to pick the chroot in autopkgtest chroot mode. This
command line option sets the CHROOT configuration variable. See sbuild.conf(5) for more
information.
--chroot-mode=schroot|sudo|autopkgtest|unshare
Select the desired chroot mode. Four values are possible: schroot (the default), sudo (which uses
sudo to execute chroot in a directory from /etc/sbuild/chroot or ./chroot), autopkgtest which uses
the autopkgtest-virt-* binaries (selectable via the --autopkgtest-virt-server option) and unshare
(which uses linux namespaces for chroot and doesn't require superuser privileges). See the
section CHROOT MODES for more information. This command line option sets the CHROOT_MODE
configuration variable. See sbuild.conf(5) for more information.
-d, --dist=distribution
Explicitly set the distribution for the package build. This will be selecting the correct chroot
to use and also sets the value of the Distribution field in the created .changes file. Setting
this option is necessary when giving sbuild a .dsc file or a plain source package name to build.
In the latter case it specifies the distribution the source package is fetched from. This command
line option sets the DISTRIBUTION configuration variable. See sbuild.conf(5) for more information.
--archive=archive
Communicate with specified archive. This command line option sets the ARCHIVE configuration
variable. See sbuild.conf(5) for more information.
-D, --debug
Enable debug output.
--apt-clean
--no-apt-clean
Run (or do not run) apt-get clean in the chroot before executing the build, overriding the default
setting. This command line option sets the APT_CLEAN configuration variable. See sbuild.conf(5)
for more information.
--apt-update
--no-apt-update
Run (or do not run) apt-get update in the chroot before executing the build, overriding the
default setting. This option has no effect on updating the internal sbuild apt repository, the
repository for extra packages (see --extra-package) and the repositories given via
--extra-repository. These are always updated. Thus, this option only influences updates of the
default repositories of the chroot. This command line option sets the APT_UPDATE configuration
variable. See sbuild.conf(5) for more information.
--apt-upgrade
--no-apt-upgrade
Run (or do not run) apt-get upgrade in the chroot before executing the build, overriding the
default setting. This command line option sets the APT_UPGRADE configuration variable. See
sbuild.conf(5) for more information.
--apt-distupgrade
--no-apt-distupgrade
Run (or do not run) apt-get distupgrade in the chroot before executing the build, overriding the
default setting. This command line option sets the APT_DISTUPGRADE configuration variable. See
sbuild.conf(5) for more information.
-m, --maintainer=maintainer
Specify the identity to use for GPG signing packages, and also used as the maintainer for binary
NMUs. This does not normally require setting (it defaults to the uploader). This command line
option sets the MAINTAINER_NAME configuration variable. See sbuild.conf(5) for more information.
-e, --uploader=uploader
Passed to dpkg-genchanges and is used to set the Changed-by: field in the .changes file(s). This
command line option sets the UPLOADER_NAME configuration variable. See sbuild.conf(5) for more
information.
-k, --keyid=key-id
Passed to debsign and is used to set the key to sign the .changes file(s). Default is not using
any key and not signing the .changes file(s). This command line option sets the KEY_ID
configuration variable. See sbuild.conf(5) for more information.
--source-only-changes
--no-source-only-changes
In addition to the .changes file generated by dpkg-buildpackage, also produce (or don't produce) a
.changes file suitable for a source-only upload. If requested by --keyid, this .changes file will
also be signed by debsign. This command line option sets the SOURCE_ONLY_CHANGES configuration
variable. See sbuild.conf(5) for more information.
-j, --jobs=n
Number of jobs to run simultaneously. Passed through to dpkg-buildpackage. This command line
option appends the appropriate -j option to the DPKG_BUILDPACKAGE_USER_OPTIONS configuration
variable. See sbuild.conf(5) for more information.
--enable-network
Enable network access during build. This command line option sets the ENABLE_NETWORK
configuration variable. See sbuild.conf(5) for more information.
--no-enable-network
Don't enable network access during build (only implemented for the unshare mode) (default). This
command line option sets the ENABLE_NETWORK configuration variable. See sbuild.conf(5) for more
information.
--debbuildopt=option
Pass the specified option directly to dpkg-buildpackage in addition to the options already passed
by sbuild. This option can be passed multiple times (once per dpkg-buildpackage option) and can be
freely mixed with the --debbuildopts option. Options will be passed to dpkg-buildpackage in the
order that the --debbuildopt and --debbuildopts options are given on the command line. This
command line option appends to the DPKG_BUILDPACKAGE_USER_OPTIONS configuration variable. See
sbuild.conf(5) for more information.
--debbuildopts=options
Pass the specified options directly to dpkg-buildpackage in addition to the options already passed
by sbuild. The argument will be split by whitespaces and the resulting array passed to the
dpkg-buildpackage invocation. If any options contain spaces, use --debbuildopt for them. This
option can be passed multiple times and can be freely mixed with the --debbuildopt option. Options
will be passed to dpkg-buildpackage in the order that the --debbuildopt and --debbuildopts options
are given on the command line. This command line option appends to the
DPKG_BUILDPACKAGE_USER_OPTIONS configuration variable. See sbuild.conf(5) for more information.
--dpkg-source-opt=options
Pass the specified option directly to dpkg-source in addition to the options already passed by
sbuild. This is only used when creating a source package from a Debianized source directory. This
option can be passed multiple times (once per dpkg-source option) and can be freely mixed with the
--dpkg-source-opts option. Options will be passed to dpkg-source in the order that the
--dpkg-source-opt and --dpkg-source-opts options are given on the command line. This command line
option appends to the DPKG_SOURCE_OPTIONS configuration variable. See sbuild.conf(5) for more
information.
NOTE: The '-b', '--before-build' and '--after-build' options will always be passed to dpkg-source,
respectively.
--dpkg-source-opts=options
Pass the specified options directly to dpkg-source in addition to the options already passed by
sbuild. The argument will be split by whitespaces and the resulting array passed to the
dpkg-source invocation. This is only used when creating a source package from a Debianized source
directory. If any options contain spaces, use --dpkg-source-opt for them. This option can be
passed multiple times and can be freely mixed with the --dpkg-source-opt option. Options will be
passed to dpkg-source in the order that the --dpkg-source-opt and --dpkg-source-opts options are
given on the command line. This command line option appends to the DPKG_SOURCE_OPTIONS
configuration variable. See sbuild.conf(5) for more information.
NOTE: The '-b', '--before-build' and '--after-build' options will always be passed to dpkg-source,
respectively.
--dpkg-file-suffix=suffix
Add the suffix to the filename of the changes and buildinfo files generated by dpkg.
NOTE: This option is ignored if dpkg-dev in the build environment is too old to support it. At
least dpkg-dev 1.18.11 is required.
--mail-log-to=email-address
Send the build log to the specified email address. This command line option sets the MAILTO
configuration variable. See sbuild.conf(5) for more information.
--mailfrom=email-address
Email address used as the sender address for build logs. This command line option sets the
MAILFROM configuration variable. See sbuild.conf(5) for more information.
-n, --nolog
Do not create a package log file in the $log_dir directory and no build log file, but print
everything to stdout. Also do not send any log mails. This command line option sets the NOLOG
configuration variable. See sbuild.conf(5) for more information.
--profiles=profile[,...]"
Specify the profile(s) we build, as a comma-separated list. Defaults to the space separated list
of profiles in the DEB_BUILD_PROFILES environment variable when building natively or the cross and
nocheck profiles when cross-building. This command line option sets the BUILD_PROFILES
configuration variable. See sbuild.conf(5) for more information.
-p, --purge=purge-mode
Convenience option to set purge-mode for build directory, build dependencies and session. This
command line option sets the PURGE_BUILD_DEPS, PURGE_BUILD_DIRECTORY and PURGE_SESSION
configuration variables. See sbuild.conf(5) for more information.
--purge-build=purge-mode
purge-mode determines if the build directory will be deleted after a build. Possible values are
always (default), never, and successful. This command line option sets the PURGE_BUILD_DIRECTORY
configuration variable. See sbuild.conf(5) for more information.
--purge-deps=purge-mode
purge-mode determines if the build dependencies will be removed after a build. Possible values are
always (default), never, and successful. This command line option sets the PURGE_BUILD_DEPS
configuration variable. See sbuild.conf(5) for more information.
--purge-session=purge-mode
Purge the schroot session following a build. This is useful in conjunction with the --purge-build
and --purge-deps options when using snapshot chroots, since by default the snapshot will be
deleted. Possible values are always (default), never, and successful. This command line option
sets the PURGE_SESSION configuration variable. See sbuild.conf(5) for more information.
-s, --source
Build the source package in addition to the other requested build artifacts. By default, the dsc
will not be rewritten because the source package is the input to sbuild, not its output. Even when
running from an unpacked source tree sbuild will first build the source package using dpkg-source
and then pass that on to the sbuild machinery. Use this option only when you know what you are
doing. This will rewrite the original dsc passed to sbuild. See the section BUILD ARTIFACTS for
more information. This command line option sets the BUILD_SOURCE configuration variable. See
sbuild.conf(5) for more information.
--no-source
Don't rebuild the source package. This is the default. It is the opposite of --source. See the
section BUILD ARTIFACTS for more information. This command line option sets the BUILD_SOURCE
configuration variable. See sbuild.conf(5) for more information.
--force-orig-source
When used with in conjunction with -s, this option forces the inclusion of the orig.tar.gz file in
the generated .changes file, even in cases where it would not normally be included, i.e. use
dpkg-buildpackage -sa. This command line option sets the FORCE_ORIG_SOURCE configuration
variable. See sbuild.conf(5) for more information.
--use-snapshot
Installs the latest snapshot gcc compiler from the gcc-snapshot package, and alters the build
environment to use the snapshot compiler for the build. Specifically, this option appends
/usr/lib/gcc-snapshot/lib to the value of the LD_LIBRARY_PATH configuration variable and
/usr/lib/gcc-snapshot/bin to the value of the PATH configuration variable. It also sets the
GCC_SNAPSHOT configuration variable. See sbuild.conf(5) for more information.
-v, --verbose
Be verbose, i.e. all information goes to stdout as well as to the log files.
-q, --quiet
Be quiet. This is the opposite of --verbose.
--make-binNMU=changelog-entry
With this option, sbuild will create a new changelog entry in debian/changelog of every package
built. The version number will be in the format for binary-only NMUs (see --binNMU); the
maintainer is set to the maintainer name configured for sbuild. changelog-entry will be used as
the changelog entry following “Binary-only non-maintainer upload for ARCH -- no source changes”.
Please note that the versions in the PACKAGE_VERSION[.dsc] arguments still have to be the
unmodified (non-NMU ones) so that the sources can be found. The version number in log files and
mails will be modified by sbuild automatically. The --append-to-version option has a similar
effect but allows one to specify an arbitrary version suffix instead of a custom changelog entry.
To have a custom version suffix and a custom changelog entry, use --make-binNMU and
--append-to-version at the same time with --binNMU=0. This option is incompatible with
--binNMU-changelog. This option implies --no-arch-all. This command line option sets the BIN_NMU
configuration variable and sets the BIN_NMU_VERSION configuration variable to 1 if it was not set
yet, for example by the --binNMU option. See sbuild.conf(5) for more information.
--binNMU=NMU-version
The version number of the binary NMU. This option only has an effect if combined with
--make-binNMU and/or with --append-to-version. version is a single number for the (+bn) format
used for binary NMUs. If the argument is the empty string or zero, then the +bn suffix will not
be appended. The +bn suffix will be appended after the string given via --append-to-version.
This option is incompatible with --binNMU-changelog. This command line option sets the
BIN_NMU_VERSION configuration variable. See sbuild.conf(5) for more information.
--append-to-version=string
This option is similar to --make-binNMU except that it allows the user to specify an arbitrary
string to be appended to the version number (immediately before the '+' in the Debian revision if
--make-binNMU is also provided). To pass an arbitrary changelog text as well, combine this option
with --make-binNMU but be aware that this will also add the +bn suffix unless you also pass
--binNMU=0 to disable it. This option is incompatible with --binNMU-changelog. This option
implies --no-arch-all. This command line option sets the APPEND_TO_VERSION configuration
variable. See sbuild.conf(5) for more information.
--binNMU-timestamp=timestamp
Set the timestamp of the new binNMU changelog entry. By default, the time of the build will be
used to generate the binNMU changelog timestamp. This option allows one to use a custom timestamp
instead. The timestamp is either given as an integer in Unix time or as a string in the format
compatible with Debian changelog entries (i.e. as it is generated by date -R). This option is
incompatible with --binNMU-changelog. This command line option sets the BIN_NMU_TIMESTAMP
configuration variable. See sbuild.conf(5) for more information.
--binNMU-changelog=changelog
Set the complete content of a binary-only changelog entry. This option allows full customization
of the new changelog entry. It is up to the user to make sure that the changelog entry is well-
formed. The argument has to include all necessary newlines. Leading and trailing newlines will be
stripped. Sbuild will not interpret any backslash escapes. This option is incompatible with
--make-binNMU, --binNMU, --append-to-version and --binNMU-timestamp. This command line option
sets the BIN_NMU_CHANGELOG configuration variable. See sbuild.conf(5) for more information.
--build-dir=directory
Set the output directory for the build artifacts created by dpkg-buildpackage and the log file. By
default, the current directory is used or, when sbuild is executed from within an unpacked source
directory, the parent directory. This command line option sets the BUILD_DIR configuration
variable. See sbuild.conf(5) for more information.
--clean-source
When executing sbuild from within an unpacked source tree, execute the debian/rules clean target.
This is the default and might require some of the build dependencies installed on the host. This
command line option sets the CLEAN_SOURCE configuration variable. See sbuild.conf(5) for more
information.
--no-clean-source
When executing sbuild from within an unpacked source tree, do not run the debian/rules clean
target before building the source package. Only set this if you start from a clean checkout and
you know what you are doing. This command line option sets the CLEAN_SOURCE configuration
variable. See sbuild.conf(5) for more information.
--run-lintian
Run lintian after a successful build. This command line option sets the RUN_LINTIAN configuration
variable. See sbuild.conf(5) for more information.
--no-run-lintian
Don't run lintian after a successful build. If sbuild is configured to run lintian by default,
this option will prevent lintian being run. This command line option sets the RUN_LINTIAN
configuration variable. See sbuild.conf(5) for more information.
--lintian-opt=options
Pass the specified option directly to lintian in addition to the options already passed by sbuild.
This option can be passed multiple times (once per lintian option) and can be freely mixed with
the --lintian-opts option. Options will be passed to lintian in the order that the --lintian-opt
and --lintian-opts options are given on the command line. This command line option appends to the
LINTIAN_OPTIONS configuration variable. See sbuild.conf(5) for more information.
--lintian-opts=options
Pass the specified options directly to lintian in addition to the options already passed by
sbuild. The argument will be split by whitespaces and the resulting array passed to the lintian
invocation. If any options contain spaces, use --lintian-opt for them. This option can be passed
multiple times and can be freely mixed with the --lintian-opts option. Options will be passed to
lintian in the order that the --lintian-opt and --lintian-opts options are given on the command
line. This command line option appends to the LINTIAN_OPTIONS configuration variable. See
sbuild.conf(5) for more information.
--run-piuparts
Run piuparts after a successful build. This command line option sets the RUN_PIUPARTS
configuration variable. See sbuild.conf(5) for more information.
--no-run-piuparts
Don't run piuparts after a successful build. If sbuild is configured to run piuparts by default,
this option will prevent piuparts being run. This command line option sets the RUN_PIUPARTS
configuration variable. See sbuild.conf(5) for more information.
--piuparts-opt=options
Pass the specified option directly to piuparts in addition to the options already passed by
sbuild. This option can be passed multiple times (once per piuparts option) and can be freely
mixed with the --piuparts-opts option. Options will be passed to piuparts in the order that the
--piuparts-opt and --piuparts-opts options are given on the command line. Certain percent escapes
are supported. To write a literal percent sign, escape it with another percent sign. See the
section OPTION STRING PERCENT ESCAPES for more information. This command line option appends to
the PIUPARTS_OPTIONS configuration variable. See sbuild.conf(5) for more information.
--piuparts-opts=options
Pass the specified options directly to piuparts in addition to the options already passed by
sbuild. The argument will be split by whitespaces and the resulting array passed to the piuparts
invocation. If any options contain spaces, use --piuparts-opt for them. This option can be passed
multiple times and can be freely mixed with the --piuparts-opts option. Options will be passed to
piuparts in the order that the --piuparts-opt and --piuparts-opts options are given on the command
line. Certain percent escapes are supported. To write a literal percent sign, escape it with
another percent sign. See the section OPTION STRING PERCENT ESCAPES for more information. This
command line option appends to the PIUPARTS_OPTIONS configuration variable. See sbuild.conf(5) for
more information.
--piuparts-root-arg=options
Add an argument that is used to launch piuparts as root. Without this option, the default is to
use "sudo --" to launch piuparts. If an empty string is supplied, then piuparts is launched
without any prefixed command. This option can be specified multiple times. This command line
option appends to the PIUPARTS_ROOT_ARGS configuration variable. See sbuild.conf(5) for more
information.
--piuparts-root-args=options
Add arguments that are used to launch piuparts as root. Without this option, the default is to
use "sudo --" to launch piuparts. If an empty string is supplied, then piuparts is launched
without any prefixed command. The argument will be split by whitespaces. To pass options
containing whitespaces use the option --piuparts-root-arg. This command line option appends to
the PIUPARTS_ROOT_ARGS configuration variable. See sbuild.conf(5) for more information.
--run-autopkgtest
Run autopkgtest after a successful build. This command line option sets the RUN_AUTOPKGTEST
configuration variable. See sbuild.conf(5) for more information.
--no-run-autopkgtest
Don't run autopkgtest after a successful build. If sbuild is configured to run autopkgtest by
default, this option will prevent autopkgtest being run. This command line option sets the
RUN_AUTOPKGTEST configuration variable. See sbuild.conf(5) for more information.
--autopkgtest-opt=options
Pass the specified option directly to autopkgtest in addition to the options already passed by
sbuild. This option can be passed multiple times (once per autopkgtest option) and can be freely
mixed with the --autopkgtest-opts option. Options will be passed to autopkgtest in the order that
the --autopkgtest-opt and --autopkgtest-opts options are given on the command line. Certain
percent escapes are supported. To write a literal percent sign, escape it with another percent
sign. See the section OPTION STRING PERCENT ESCAPES for more information. This command line
option appends to the AUTOPKGTEST_OPTIONS configuration variable. See sbuild.conf(5) for more
information.
--autopkgtest-opts=options
Pass the specified options directly to autopkgtest in addition to the options already passed by
sbuild. The argument will be split by whitespaces and the resulting array passed to the
autopkgtest invocation. If any options contain spaces, use --autopkgtest-opt for them. This
option can be passed multiple times and can be freely mixed with the --autopkgtest-opts option.
Options will be passed to autopkgtest in the order that the --autopkgtest-opt and
--autopkgtest-opts options are given on the command line. Certain percent escapes are supported.
To write a literal percent sign, escape it with another percent sign. See the section OPTION
STRING PERCENT ESCAPES for more information. This command line option appends to the
AUTOPKGTEST_OPTIONS configuration variable. See sbuild.conf(5) for more information.
--autopkgtest-root-arg=options
Add an argument that is used to launch autopkgtest as root. Without this option, the default is to
use "sudo --" to launch autopkgtest. If an empty string is supplied, then autopkgtest is launched
without any prefixed command. This option can be specified multiple times. This command line
option appends to the AUTOPKGTEST_ROOT_ARGS configuration variable. See sbuild.conf(5) for more
information.
--autopkgtest-root-args=options
Add arguments that are used to launch autopkgtest as root. Without this option, the default is to
use "sudo --" to launch autopkgtest. If an empty string is supplied, then autopkgtest is launched
without any prefixed command. The argument will be split by whitespaces. To pass options
containing whitespaces use the option --autopkgtest-root-arg. This command line option appends to
the AUTOPKGTEST_ROOT_ARGS configuration variable. See sbuild.conf(5) for more information.
--pre-build-commands=string
This is the earliest external command which is run right after the chroot session has been
initialized and before anything else is done (like installing the build dependencies). The command
is run outside of the chroot. This option can be used multiple times to add multiple commands.
Certain percent escapes are supported. To write a literal percent sign, escape it with another
percent sign. See the section EXTERNAL COMMANDS for more information. This command line option
appends to the EXTERNAL_COMMANDS configuration variable. See sbuild.conf(5) for more information.
--chroot-setup-commands=string
Run these commands after the chroot and variables have been setup but before dependencies are
installed. The command is run as root inside of the chroot. This option can be used multiple
times to add multiple commands. Certain percent escapes are supported. To write a literal percent
sign, escape it with another percent sign. See the section EXTERNAL COMMANDS for more information.
This command line option appends to the EXTERNAL_COMMANDS configuration variable. See
sbuild.conf(5) for more information.
--chroot-update-failed-commands=string
Run these commands after any of 'apt-get update', 'apt-get upgrade' or 'apt-get dist-upgrade'
failed. This hook is not run for updates of the internal sbuild apt repository, the repository
for extra packages (see --extra-package) and the repositories given via --extra-repository. The
environment is intact, and the failure can be investigated. Especially %SBUILD_SHELL is useful
here. This option can be used multiple times to add multiple commands. Certain percent escapes are
supported. To write a literal percent sign, escape it with another percent sign.See the section
EXTERNAL COMMANDS for more information. This command line option appends to the EXTERNAL_COMMANDS
configuration variable. See sbuild.conf(5) for more information.
--build-deps-failed-commands=string
These commands are run if installing the build dependencies has failed directly after the failed
attempt. The environment is intact, and the failure can be investigated. Especially %SBUILD_SHELL
is useful here. The command is run as root inside the chroot. This option can be used multiple
times to add multiple commands. Certain percent escapes are supported. To write a literal percent
sign, escape it with another percent sign. See the section EXTERNAL COMMANDS for more information.
This command line option appends to the EXTERNAL_COMMANDS configuration variable. See
sbuild.conf(5) for more information.
--starting-build-commands=string
Run these commands after dependencies are installed, just before the package build with
dpkg-buildpackage starts. The command is run as the root user inside the chroot. This option can
be used multiple times to add multiple commands. Certain percent escapes are supported. To write a
literal percent sign, escape it with another percent sign. See the section EXTERNAL COMMANDS for
more information. This command line option appends to the EXTERNAL_COMMANDS configuration
variable. See sbuild.conf(5) for more information.
--finished-build-commands=string
Run these commands immediately after the timed package build finishes. The command is run as the
root user inside the chroot. This option can be used multiple times to add multiple commands.
Certain percent escapes are supported. To write a literal percent sign, escape it with another
percent sign. See the section EXTERNAL COMMANDS for more information. This command line option
appends to the EXTERNAL_COMMANDS configuration variable. See sbuild.conf(5) for more information.
--build-failed-commands=string
These commands are run if dpkg-buildpackage has failed directly after the failed attempt. The
environment is intact, and the failure can be investigated. Especially %SBUILD_SHELL is useful
here. The command is run as the root user inside the chroot. This option can be used multiple
times to add multiple commands. Certain percent escapes are supported. To write a literal percent
sign, escape it with another percent sign. See the section EXTERNAL COMMANDS for more information.
This command line option appends to the EXTERNAL_COMMANDS configuration variable. See
sbuild.conf(5) for more information.
--chroot-cleanup-commands=string
Run these commands when a chroot is cleaned up, before build directory is purged. The command is
run as root inside the chroot. This option can be used multiple times to add multiple commands.
Certain percent escapes are supported. To write a literal percent sign, escape it with another
percent sign. See the section EXTERNAL COMMANDS for more information. This command line option
appends to the EXTERNAL_COMMANDS configuration variable. See sbuild.conf(5) for more information.
--post-build-commands=string
Run this command after a successful build. The command is run outside of the chroot. This option
can be used multiple times to add multiple commands. Certain percent escapes are supported. To
write a literal percent sign, escape it with another percent sign. See the section
--post-build-failed-commands=string
Exactly like the above, but when a build fails. EXTERNAL COMMANDS for more information. This
command line option appends to the EXTERNAL_COMMANDS configuration variable. See sbuild.conf(5)
for more information.
--anything-failed-commands=string
Run these commands for all the --xxx-failed-commands options. Especially %SBUILD_SHELL is useful
here. This option can be used multiple times to add multiple commands. Certain percent escapes are
supported. To write a literal percent sign, escape it with another percent sign. See the section
EXTERNAL COMMANDS for more information. This command line option appends to the EXTERNAL_COMMANDS
configuration variable. See sbuild.conf(5) for more information.
--log-external-command-output
Write output from external commands to the build log. This command line option sets the
LOG_EXTERNAL_COMMAND_OUTPUT configuration variable. See sbuild.conf(5) for more information.
--log-external-command-error
Write error output from external commands to the build log. This command line option sets the
LOG_EXTERNAL_COMMAND_ERROR configuration variable. See sbuild.conf(5) for more information.
--setup-hook=hook-script DEPRECATED
This option is deprecated. Use of this option will add hook-script to the external commands to run
via chroot-setup-commands. This command line option sets the CHROOT_SETUP_SCRIPT configuration
variable and appends to the EXTERNAL_COMMANDS configuration variable. See sbuild.conf(5) for more
information.
--build-dep-resolver=resolver
Use the specified resolver to handle selecting the build dependencies. Supported resolvers are
apt (the default), aptitude, aspcud, xapt, and null. The apt resolver is the most appropriate
resolver for most users, for building for unstable, stable and other distributions. If
alternative build dependencies are used (excluding architecture restrictions), only the first
alternative will be used; the others will be ignored. The aptitude resolver is very similar, but
smarter and slower, and it will consider all alternatives by default; it is suited to more complex
situations, such as building packages for the experimental distribution, where packages need
installing from multiple suites (unstable and experimental). Due to performance issues, aptitude
is not recommended for use by default. If the dependency situation is so complex that neither apt
nor aptitude are able to find a solution, then you can use the aspcud resolver. This resolver
uses apt-cudf to ask aspcud, a real solver (in the math sense), to find a solution to the
installation problem. Since aspcud uses a real solver (an ASP solver) it will always find a
solution if one exists. The solution found by the aspcud resolver can be refined by changing the
default optimization criteria through the --aspcud-criteria option. The xapt resolver is intended
only for cross-building, and is a temporary transitional feature which will be removed following
the complete introduction of multi-arch support. Finally, the null resolver is a dummy solver
which does not install, upgrade or remove any packages. This allows one to completely control
package installation via hooks. This command line option sets the BUILD_DEP_RESOLVER
configuration variable. See sbuild.conf(5) for more information.
--aspcud-criteria=criteria
Optimization criteria in extended MISC 2012 syntax passed to aspcud through apt-cudf.
Optimization criteria are separated by commas, sorted by decreasing order of priority and are
prefixed with a polarity (+ to maximize and - to minimize). The default criteria is
-removed,-changed,-new which first minimizes the number of removed packages, then the number of
changed packages (up or downgrades) and then the number of new packages. A common task is to
minimize the number of packages from experimental. To do this you can add a criteria like
-count(solution,APT-Release:=/a=experimental/) to the default criteria. This will then minimize
the number of packages in the solution which contain the string a=experimental in the APT-Release
field of the EDSP output created by apt. For more help on how to write optimization criteria, see
the apt-cudf(1) man page. Specifically the help on the --criteria option. This command line
option sets the ASPCUD_CRITERIA configuration variable. See sbuild.conf(5) for more information.
--resolve-alternatives
Allow the use of alternatives in Build-Depends, Build-Depends-Arch and Build-Depends-Indep. This
is the default for the aptitude dependency resolver. This command line option sets the
RESOLVE_ALTERNATIVES configuration variable. See sbuild.conf(5) for more information.
--no-resolve-alternatives
Do not allow the use of alternatives in Build-Depends, Build-Depends-Arch and Build-Depends-Indep.
Note that alternatives for the same package (e.g. different versions) are still allowed. This is
the default for the apt and xapt dependency resolvers. This command line option sets the
RESOLVE_ALTERNATIVES configuration variable. See sbuild.conf(5) for more information.
--extra-package=package.deb|directory
Make package.deb available for build-dependency resolution, by adding it to a temporary archive
created by sbuild. This makes it easier to build packages against locally-built build
dependencies, without waiting for those packages to enter the main archive, or going through the
hassle of maintaining a local archive and making it accessible inside the chroot. package.deb is
copied into the chroot, so it can refer to any path on the host system. If a directory is passed
instead of a regular file, then all regular files inside that directory with a filename that ends
in .deb will be added in the same fashion as it is done for individual packages. This option can
be specified multiple times. This command line option appends to the EXTRA_PACKAGES configuration
variable. See sbuild.conf(5) for more information.
--extra-repository=spec
Add a repository to the list of apt sources during the package build. The repository
specification is a line suitable for an apt sources.list(5) file. For instance, you might use
--extra-repository="deb http://deb.debian.org/debian experimental main" to allow packages in the
experimental distribution to fulfill build-dependencies. Note that the build chroot must already
trust the key of this repository or a key must be given with the --extra-repository-key flag (see
apt-secure(8)). This command line option appends to the EXTRA_REPOSITORIES configuration
variable. See sbuild.conf(5) for more information.
--extra-repository-key=file.asc
Add file.asc to the list of trusted keys inside the chroot. The key is read from the filename
given, and added to the trusted keys. For more information, see apt-secure(8). This flag is
particularly useful if the target in --extra-repository is not signed with a key that's trusted by
the base chroot. This command line option appends to the EXTRA_REPOSITORY_KEYS configuration
variable. See sbuild.conf(5) for more information.
--build-path=string
By default the package is built in a path of the following format
/build/packagename-XXXXXX/packagename-version/ where XXXXXX is a random ascii string. This option
allows one to specify a custom path where the package is built inside the chroot. The sbuild user
in the chroot must have permissions to create the path. Common writable locations are
subdirectories of /tmp or /build. Using /tmp might be dangerous, because (depending on the chroot
mode) the /tmp inside the chroot might be a world writable location that can be accessed by
processes outside the chroot. The directory /build can only be accessed by the sbuild user and
group and should be a safe location. The buildpath must be an empty directory because the last
component of the path will be removed after the build is finished. Notice that depending on the
chroot mode (see --chroot-mode), some locations inside the chroot might be bind mounts that are
shared with other sbuild instances. You must avoid using these shared locations as the build path
or otherwise concurrent runs of sbuild will likely fail. With the default schroot chroot mode, the
directory /build is shared between multiple schroot sessions. You can change this behaviour in
/etc/schroot/sbuild/fstab. The behaviour of other chroot modes will vary. This command line
option sets the BUILD_PATH configuration variable. See sbuild.conf(5) for more information.
--dsc-dir=string
By default the package is built in a path of the following format
/build/packagename-XXXXXX/packagename-version/ where packagename-version are replaced by the
values in debian/changelog. This option allows one to specify a custom packagename-version path
where the package is built inside the chroot. This is useful to specify a static path for
different versions for example for ccache. This command line option sets the DSC_DIR
configuration variable. See sbuild.conf(5)formoreinformation.
--autopkgtest-virt-server=schroot|lxc|chroot|qemu|ssh
The autopkgtest virtualization server. Can be specified with or without the autopkgtest-virt-
prefix. For instance, the following set of command line options will use the
autopkgtest-virt-schroot chroot mode for a package build: --chroot-mode=autopkgtest
--autopkgtest-virt-server=schroot --autopkgtest-virt-server-opt=unstable-amd64-sbuild This command
line option sets the AUTOPKGTEST_VIRT_SERVER configuration variable. See sbuild.conf(5) for more
information.
--autopkgtest-virt-server-opt=string
Pass the specified option directly to the respective autopkgtest-virt-* virtualization server in
addition to the options already passed by sbuild. This option can be passed multiple times (once
per autopkgtest-virt-* option) and can be freely mixed with the --autopkgtest-virt-server-opts
option. Options will be passed to the respective autopkgtest-virt-* virtualization server in the
order that the --autopkgtest-virt-server-opt and --autopkgtest-virt-server-opts options are given
on the command line. See the manual pages of the respective autopkgtest-virt-* commands for more
information. Certain percent escapes are supported. To write a literal percent sign, escape it
with another percent sign. See the section OPTION STRING PERCENT ESCAPES for more information.
This command line option appends to the AUTOPKGTEST_VIRT_SERVER_OPTIONS configuration variable.
See sbuild.conf(5) for more information.
--autopkgtest-virt-server-opts=options
Pass the specified options directly to the respective autopkgtest-virt-* virtualization server in
addition to the options already passed by sbuild. The argument will be split by whitespaces and
the resulting array passed to the autopkgtest-virt-* invocation. If any options contain spaces,
use --autopkgtest-virt-server-opt for them. This option can be passed multiple times and can be
freely mixed with the --autopkgtest-virt-server-opts option. Options will be passed to the
respective autopkgtest-virt-* virtualization server in the order that the
--autopkgtest-virt-server-opt and --autopkgtest-virt-server-opts options are given on the command
line. See the manual pages of the respective autopkgtest-virt-* commands for more information.
Certain percent escapes are supported. To write a literal percent sign, escape it with another
percent sign. See the section OPTION STRING PERCENT ESCAPES for more information. This command
line option appends to the AUTOPKGTEST_VIRT_SERVER_OPTIONS configuration variable. See
sbuild.conf(5) for more information.
--sbuild-mode=mode
Behaviour changes for use in a buildd environment. This command line option sets the SBUILD_MODE
configuration variable. See sbuild.conf(5) for more information.
--stats-dir=directory
Directory for writing build statistics to. This command line option sets the STATS_DIR
configuration variable. See sbuild.conf(5) for more information.
--purge-extra-packages
This is an experimental option. Only use when you know what you are doing. Source packages must
be buildable with only their build dependencies, all packages marked as Essential:yes, the
build-essential package and their transitive dependencies installed. But by default, most chroots
will also include Priority:required packages and apt as well as their transitive dependencies.
This option will try to remove all additional packages that are not strictly required for the
build right after build dependencies were installed. This currently works best with the aspcud
resolver. The apt resolver will not make as much effort to remove all unneeded packages and will
keep all providers of a virtual package and all packages from any dependency alternative that
happen to be installed. The aptitude and xapt resolver do not implement this feature yet. The
removed packages are not (yet) added again after the build finished. This can have undesirable
side effects like lintian not working (because there is no apt to install its dependencies) or
bare chroots becoming totally unusable after apt was removed from them. Thus, this option should
only be used with throw-away chroots like schroot provides them where the original state is
automatically restored after each build. This command line option sets the PURGE_EXTRA_PACKAGES
configuration variable. See sbuild.conf(5) for more information.
--bd-uninstallable-explainer=dose3|apt|none
If the build dependencies cannot be satisfied by the chosen resolver, sbuild will run the selected
method to give a better explanation why the build dependencies cannot be installed. Possible
arguments for this option are dose3 (the default), apt and none. To disable this feature, pass
none or the empty string. Depending on the resolver, the dose3 explainer might report a
dependency situation as satisfiable even if the chosen resolver found it to be unsatisfiable. This
is especially likely to happen if the apt resolver (the default) is used. Such disparities can
have two reasons: either the understanding of the involved dependency situation of the apt and
dose3 solver differs (this is a bug) or the apt solver was unable to find a solution if the
dependency situation is not trivial (for example if it involves packages from multiple
repositories). In the former case, please report the disparity as a bug against the resolvers. In
the latter case, use a resolver that is more likely to find a solution like the aptitude or aspcud
resolvers. Especially the aspcud resolver should find a solution if and only if the dose3 solver
also finds one. This command line option sets the BD_UNINSTALLABLE_EXPLAINER configuration
variable. See sbuild.conf(5) for more information.
CHROOT MODES
The main purpose of sbuild is to build Debian packages in a clean chroot environment. Provisioning and
managing these chroot environments is not done by sbuild itself but by multiple backends. The default
backend (or chroot mode) is schroot which is an suid binary that allows regular users to enter a chroot
environment. But sbuild also allows one to build packages in a qemu virtual machine, lxc, lxd or on a
remote host reached by ssh using the autopkgtest backend. The backend can be chosen using the
--chroot-mode command line argument or the $chroot_mode configuration parameter.
schroot
The default and recommended chroot mode. It is also used on Debian buildd machines. The easiest
way to set up sbuild for use with the schroot backend is by using sbuild-createchroot which will
also write out the necessary schroot configuration files in /etc. To use the chroots, the current
user has to be added to the sbuild group, for example by running sbuild-adduser. Updating these
schroot backends can be done using sbuild-update. See the respective man pages for more
information about how to use these programs. Schroot supports chroots from directories, tarballs,
filesystem images and block devices. Schroot provides ephemeral chroots either by unpacking a
tarball into a temporary directory, by using an overlay filesystem for directory chroots or by
using btrfs or lvm snapshots. Chroots usable by schroot are defined by configuration files in
/etc/schroot/chroot.d/. When building for a specific distribution and architecture, sbuild will
choose the chroot that is named (or has the alias) $distribution-$arch-sbuild,
$distribution-sbuild, $distribution-$arch or $distribution, in that order of preference. The used
chroot name can be overridden using the -c or --chroot options.
sudo It operates by plainly entering the chosen chroot directory using "sudo chroot". Thus, this
backend also does not provide ephemeral chroots. The sudo chroot mode searches for a symlink or
directory located at /etc/sbuild/chroot/ or in the current directory, prefixed with chroot-. The
expected names are resolved in the same order as for the schroot chroot mode and can be overridden
using the -c or --chroot options.
autopkgtest
This is an experimental chroot mode that allows one to build packages in any chroot supported by
autopkgtest. This allows one to build packages in lxc or lxd containers, a qemu virtual machine or
on a remote host via ssh. Which autopkgtest server to use is determined via the
--autopkgtest-virt-server option. Since autopkgtest (in contrast to schroot) does not maintain a
registry of available containers or (virtual) machines, it is necessary to manually specify them
using the --autopkgtest-virt-server-opts= command line argument. To avoid having to manually type
the right container or machine name every time when sbuild is executed, percent escapes are
permitted.
unshare
This backend allows one to build packages inside chroots provided by arbitrary tarballs without
superuser privileges. This allows one to set up an arbitrary build environment without having to
become root. Building packages with schroot also doesn't require sudo (schroot is suid root) but
setting up and updating chroots requires superuser permissions. The unshare backend only makes use
of two small suid binaries (newuidmap and newgidmap). This backend allows arbitrary tarballs
containing chroot environments to be used for package building. The default tarball location is in
~/.cache/sbuild/. The expected names are resolved in the same order as for the schroot chroot mode
and can be overridden using the -c or --chroot options.
On buster and earlier Debian releases, unprivileged userns clones
(/proc/sys/kernel/unprivileged_userns_clone) were disabled by default by means of a Debian-
specific kernel patch. On these systems, root is required for enabling them. This can also done
permanently by setting kernel.unprivileged_userns_clone=1 in /etc/sysctl.d/.
BUILD ARTIFACTS
Sbuild is meant to be used to build architecture specific binary packages from a given source package. In
addition, sbuild is also able to generate architecture independent binary packages as well as to rebuild
the original source package that was used as input. In summary, sbuild is able to build architecture
specific binary packages, architecture independent binary packages and source packages. What ends up
being built is determined by the configuration variables BUILD_ARCH_ANY, BUILD_ARCH_ALL and BUILD_SOURCE,
respectively. See sbuild.conf(5) for a detailed explanation of these configuration variables.
By default, during native compilation, BUILD_ARCH_ANY and BUILD_ARCH_ALL are set to true while
BUILD_SOURCE is set to false. During cross-compilation, BUILD_ARCH_ALL defaults to false. This
behaviour can be changed either by using command line options or by modifying the configuration variables
in your ~/.sbuildrc. The relevant command line options to change the values of BUILD_ARCH_ANY,
BUILD_ARCH_ALL and BUILD_SOURCE are --arch-any/--no-arch-any, --arch-all/--no-arch-all and
--source/--no-source, respectively.
The values of BUILD_ARCH_ANY, BUILD_ARCH_ALL and BUILD_SOURCE change the parameter that dpkg-buildpackage
is called with. The following table displays the argument passed to dpkg-buildpackage in the last column
depending on the configuration options in the first three columns.
BUILD_ARCH_ANY BUILD_ARCH_ALL BUILD_SOURCE dpkg-buildpackage flag
────────────────────────────────────────────────────────────────────────
false false false invalid
false false true -S
false true false -A
false true true -g
true false false -B
true false true -G
true true false -b
true true true no option
EXTERNAL COMMANDS
Support to run external commands during an sbuild run is provided. A set of external commands can be run
at various stages of a build. Providing commands to run is done through the appropriate options given on
the command line and through the use of the configuration files. In the configuration file, the list of
commands to run are placed in a hash of arrays of arrays of strings corresponding to the commands to run.
There are several sets of commands. All command are run inside the chroot as root except for the
pre/post-build- commands which are run as the user running sbuild outside of the chroot. To run an
external command as another user than the root user, prefix your command with runuser -u sbuild --.
Here is a summary of the ordering, user, internal/external to chroot for each command hook
The following table shows each command hook in the context of the tasks sbuild performs. The column root
shows whether the command is run as root (yes) or not (no). The column chroot shows whether the command
is run inside our outside the chroot. The working directory inside the chroot is the one marked with
<<BUILDDIR>> inside the log. By default, this is a directory of the format /build/packagename-XXXXXX/
where XXXXXX is a random ascii string. Otherwise, it is the directory set by --build-path or by the
BUILD_PATH configuration option. The working directory outside of the chroot is $HOME. The remaining
columns show the percent escapes that are defined in each command. Percent escapes that are available in
all commands (%%, %a, %b, %s) are omitted. The value maybe in the column for the %d and %p escapes means
that the value can not relied upon to be defined in these stages. More specifically, these escapes will
not be defined at these points if the user specified a source package name without a version on the
command line. In that case, the version will only become known after the source package has been
retrieved in the "Fetch and unpack source package" stage.
command/action root chroot %c %e %d,%p
──────────────────────────────────────────────────────────────────────────
Initialise chroot session
--pre-build-commands no outside no yes maybe
Setup the chroot and variables
--chroot-setup-commands yes inside no no maybe
Update and upgrade packages
--chroot-update-failed-commands yes inside no no maybe
Fetch and unpack source package
Install Dependencies
--build-deps-failed-commands yes inside no no yes
--starting-build-commands yes inside no no yes
Run dpkg-buildpackage
--build-failed-commands yes inside no no yes
--finished-build-commands yes inside no no yes
Run lintian (if configured)
--chroot-cleanup-commands yes inside yes no yes
Cleanup build files and dependencies
Run piuparts (if configured)
Run autopkgtest (if configured)
Close schroot session
--post-build-commands no outside yes yes yes
--post-build-failed-commands no outside yes yes yes
The commands can be given in the configuration files. They can be given as strings or as a list of
arguments. For example, to run "foo" and "bar" with arguments before a build starts, specifying the "foo"
command as a list and "bar" as a string, one could do this:
$external_commands = {
"pre-build-commands" => [
['foo', 'arg1', 'arg2'],
'bar arg1 arg2 arg3',
],
};
Hash keys for commands to run at other stages have the same name as their corresponding command-line
option name without the preceding '--'.
Here's an example of how to do the same with the previous example, except using the --pre-build-commands
option.
$ sbuild \
--pre-build-commands='foo arg1 arg2' \
--pre-build-commands='bar arg1 arg2 arg3'
Note that all these commands are executed through the shell in "/bin/sh". If specifying the command as a
list in the config file, very few shell facilities are supported: no redirection, no command
concatenation with ; and so on. When passing a string (in the config file or on the commandline), the
string is passed as-is to the shell. So all shell facilities are available, given that you escape
everything properly, as you would in an interactive shell.
Besides running external commands, sbuild can also detect the use of certain percent escapes given as
arguments. These are used to allow for a command to be supplied with a certain argument depending on the
escape given. For example, it could be possible to have an external command be given the path to a
.changes file.
Here is a listing of keywords and a description of what it's converted to.
%% Used to escape a '%'.
%d, %SBUILD_DSC
These escapes are converted to the absolute path to a package's .dsc file.
%c, %SBUILD_CHANGES
These escapes are converted to the absolute path to a package's source .changes file. This is the
.changes file generated by the dpkg-buildpackage invocation and not the source-only .changes file
that might've been produced additionally via --source-only-changes. This variable is only set
after the build is finished, i.e in --chroot-cleanup-commands, --post-build-commands, and
--post-build-failed-commands.
%a, %SBUILD_HOST_ARCH
These escapes are converted to the debian name of the architecture the build is being built for
(e.g amd64, armhf).
%e, %SBUILD_CHROOT_EXEC
These escapes are converted to a command which can be executed on a host and can be given
arguments which will then be executed inside the chroot. Standard input and output of the process
started inside the chroot are connected to the program executed on the host. Thus, this command
can also be used to copy data into the chroot and out of the chroot. The working directory of the
process started inside the chroot is the root directory of the chroot. The process is started as
the root user. This variable is not set if the external command is run inside the chroot. Thus
this escape is only available for --pre-build-commands, --post-build-commands, and
--post-build-failed-commands.
%b, %SBUILD_BUILD_DIR
These escapes are converted to the absolute path to the build directory inside the chroot.
%p, %SBUILD_PKGBUILD_DIR
These escapes are converted to the absolute path to the package build directory inside the chroot.
%s, %SBUILD_SHELL
This is converted to a command to spawn an interactive "bash" shell
%SBUILD_BUILD_ARCH
This escape is converted to the Debian name of the architecture that the build is being run on
(e.g amd64, armhf).
Percent escapes are only substituted when an appropriate value is defined for them. At other times, it is
left unchanged. In practice this means that there are only two escapes that are not available in all
external commands: %c and %e. For example, a .changes file is only defined at the end of a build, so
using %c will only be substituted for post-build-commands and post-build-failed-commands.
Here's an example of using an escape to run a program foo on a .changes file after a build is done.
$ sbuild --post-build-commands \
'foo %SBUILD_CHANGES'
And here's an example that will spawn an interactive shell to investigate the problem whenever the build
failed:
$ sbuild --build-failed-commands '%SBUILD_SHELL'
The following example would copy a file from the host into the chroot:
$ sbuild --pre-build-commands \
'cat blub.txt | %SBUILD_CHROOT_EXEC sh -c "cat > blub.txt"'
One final note, external commands are processed in the order they are given. Also, the commands given in
a configuration file are processed first, then the commands given through the command line options.
OPTION STRING PERCENT ESCAPES
Besides for external command strings, percent escapes can also be used in custom options passed to
piuparts, autopkgtest and the chosen autopkgtest-virt server. This is for example useful for
communicating the right chroot backend to piuparts or autopkgtest depending on the distribution or
architecture the source package was built for.
Here is a listing of keywords and a description of what it's converted to.
%% Used to escape a '%'.
%a, %SBUILD_HOST_ARCH
These escapes are converted to the debian name of the architecture the build is being built for
(e.g amd64, armhf).
%r, %SBUILD_DISTRIBUTION
The distribution that the source package was built for. This is the value recorded in
debian/changelog or the value passed via the --dist option. Mnemonic: the r is the first letter
in "release".
Here is an example that will run piuparts with the right schroot chroot:
$ sbuild --run-piuparts \
--piuparts-opts="--schroot=%r-%a-sbuild"
Or an example of running autopkgtest with the right schroot chroot:
$ sbuild --run-autopkgtest --autopkgtest-root-args= \
--autopkgtest-opts="-- schroot %r-%a-sbuild"
To achieve the same effect via the configuration file, add the following:
$autopkgtest_root_args = '';
$piuparts_opts = [ '--schroot=%r-%a-sbuild' ];
$autopkgtest_opts = [ '--', 'schroot', '%r-%a-sbuild' ];
The --autopkgtest-root-args option and the $autopkgtest_root_args configuration variable are set to the
empty string because the default is to run autopkgtest with "sudo --" in front of it which is not needed
with the schroot autopkgtest backend.
LOCAL ARCHIVE
The apt and aptitude resolvers create a local archive for installing build dependencies. This is an
internal implementation detail of the build dependency resolver, which is not user configurable, and is
intended to be entirely transparent to the user. The local archive exists only transiently during the
package build. It does not persist across builds, and it is only used to store the dummy dependency
packages created for a single build.
The dependency resolvers do the following:
• Create a dummy dependency package. This contains the Build-Depends (and optionally
Build-Depends-Arch and Build-Depends-Indep) as Depends, and Build-Conflicts (and optionally
Build-Conflicts-Arch and Build-Conflicts-Indep) as Conflicts.
• Install the dummy dependency package into the local archive,
• Generate the Packages, Sources and Release files.
• Write a sources.list file for the local archive into /etc/apt/sources.list.d.
• Inject the lists directly into /var/lib/apt/lists. This step is to save running updating all apt
sources which is undesirable during a build; apt and aptitude do not support updating a single
source at present.
• Regenerate the apt caches to ensure everything is in sync.
• Install the dummy dependency package with apt or aptitude; the dummy package is pulled from the
local apt archive, while all its dependencies are pulled from the regular configured apt sources.
At the end of the build, the local archive is removed, along with the rest of the build tree.
EXAMPLES
Before you use sbuild for the first time, you have to do some setup depending on the chroot mode you are
using. The default chroot mode is schroot. To use sbuild with the schroot backend, you need to add your
user to the sbuild group and create a schroot chroot. The latter can be accomplished by using
sbuild-createchroot(8). After this one time setup, you can now use sbuild to build packages like this:
% sbuild -d unstable bash
Or on a .dsc:
% sbuild -d unstable bash.dsc
Or from within an unpacked source package (the -d parameter is not necessary here because the
distribution is inferred from debian/changelog):
% sbuild
ENVIRONMENT VARIABLES
The following environment variables are used by sbuild:
HOME The home directory of the user.
LOGNAME
Used in lockfiles.
SBUILD_CONFIG
Path to an additional configuration file on top of the system wide and user specific ones.
FILES
/etc/sbuild/sbuild.conf
Configuration, maintained by the system administrator. This may be used to override the defaults.
/etc/sbuild/chroot
Directory containing symbolic links to chroots. This is only used for sudo chroot access; schroot
access uses the schroot chroot configuration.
~/.sbuildrc
User-specific configuration. A custom path to a configuration file can also be specified through
setting the SBUILD_CONFIG environment variable to the path of an additional configuration file.
/var/lib/sbuild
Build trees, archive signing keys, build statistics and lock files.
AUTHORS
Roman Hodek <Roman.Hodek@informatik.uni-erlangen.de>.
sbuild is based on debbuild, written by James Troup <james@nocrew.org> and has been modified by
Ben Collins <bcollins@debian.org>,
Ryan Murray <rmurray@debian.org>,
Francesco Paolo Lovergine <frankie@debian.org>,
Michael Banck <mbanck@debian.org>, and
Roger Leigh <rleigh@debian.org>
COPYRIGHT
Copyright © 1998-2000 Roman Hodek <roman@hodek.net>
Copyright © 1998-1999 James Troup <troup@debian.org>
Copyright © 2003-2006 Ryan Murray <rmurray@debian.org>
Copyright © 2001-2003 Rick Younie <younie@debian.org>
Copyright © 2003-2004 Francesco Paolo Lovergine <frankie@debian.org>
Copyright © 2005 Michael Banck <mbanck@debian.org>
Copyright © 2005-2009 Roger Leigh <rleigh@debian.org>
SEE ALSO
sbuild.conf(5), sbuild-abort(1), sbuild-adduser(8), sbuild-apt(1), sbuild-checkpackages(1),
sbuild-createchroot(8), sbuild-distupgrade(1), sbuild-hold(1), sbuild-setup(7). sbuild-shell(1),
sbuild-unhold(1), sbuild-update(1), sbuild-upgrade(1), schroot(1),