sbuild - Online in the Cloud

PROGRAM:

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] [--arch=architecture]
[--arch-any | --no-arch-any] [--arch-all-only] [--build=architecture]
[--host=architecture] [--profiles=profile[,...]] [-s|--source] [--force-orig-source]
[--make-binNMU=changelog-entry] [--binNMU=NMU-version] [--append-to-version=string]
[--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] [-j|--jobs=n] [--debbuildopt=option] [--debbuildopts=options] [--dpkg-
source-opt=options] [--dpkg-source-opts=options] [-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] [--pre-build-commands=string]
[--chroot-setup-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] [--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] [--extra-repository=spec] [--extra-repository-key=file.asc]
[--build-path=string] [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 (chroot), rather than on the host system.

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, 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, 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.

Note: When using schroot (recommended), the chroot having the name (or alias) of the
specified distribution will be used; schroot uses a chroot named $distribution-$arch-
sbuild, $distribution-sbuild, $distribution-$arch or $distribution, in that order of
preference. The -c or --chroot option may be used to override the chroot to be used. When
configured to use sudo (deprecated), sbuild will look for a symlink to a chroot with the
same name as the distribution specified. sbuild will use a symlink to the chroot located
in /etc/sbuild/chroot/$distribution, or must be run in a directory containing a
chroot-$distribution symlink to the chroot (not recommended, but done for backward
compatibility).

OPTIONS

-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.

--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".

--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.

--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.

-A, --arch-all
Also build Architecture: all packages, i.e. use dpkg-buildpackage -b instead of -B.

--no-arch-all
Do not build Architecture: all packages, i.e. use dpkg-buildpackage -B instead of
-b. This option is the opposite of --arch-all.

--arch-any
Build Architecture: any packages. This is the default behavior.

--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.

--arch-all-only
Only build Architecture:all packages, i.e. use dpkg-buildpackage -A instead of -B.
The --arch=architecture option can still be used to specify the architecture used
to build the package.

-b, --batch
Operate in batchmode, i.e. write a build-progress file during execution and files
on shutdown to facilitate a clean restart.

-c, --chroot=chroot
Use the specified chroot. If not specified, the default is the first of
$distribution-$arch-sbuild, $distribution-sbuild, $distribution-$arch or
$distribution that exists.

-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.

--archive=archive
Communicate with specified archive.

-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.

--apt-update
--no-apt-update
Run (or do not run) apt-get update in the chroot before executing the build,
overriding the default setting.

--apt-upgrade
--no-apt-upgrade
Run (or do not run) apt-get upgrade in the chroot before executing the build,
overriding the default setting.

--apt-distupgrade
--no-apt-distupgrade
Run (or do not run) apt-get distupgrade in the chroot before executing the build,
overriding the default setting.

-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).

-e, --uploader=uploader
Passed to dpkg-genchanges and is used to set the Changed-by: field in the .changes
file(s).

-k, --keyid=key-id
Passed to dpkg-genchanges and is used to set the key to sign the .changes file(s).
Default is not using any key.

-j, --jobs=n
Number of jobs to run simultaneously. Passed through to dpkg-buildpackage.

--debbuildopt=option
Pass the specified option directly to dpkg-buildpackage.

--debbuildopts=options
Pass the specified options directly to dpkg-buildpackage. The options should be
separated by spaces. If any options contain spaces, use --debbuildopt instead.

--dpkg-source-opt=options
Pass the specified options directly to dpkg-source. This is only used when creating
a source package from a Debianized source directory.
NOTE: The '-b' option will always be passed to dpkg-source.

--dpkg-source-opts=options
Extra options to be appended to existing options passed to dpkg-source.

--mail-log-to=email-address
Send the build log to the specified email address. This overrides the $mailto
configuration option.

--mailfrom=email-address
Email address used as the sender address for build logs. This overrides the
$mailfrom configuration option.

-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.

-p, --purge=purge-mode
Convenience option to set purge-mode for build directory, build dependencies and
session.

--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.

--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.

--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.

--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.

-s, --source
Also build source package, i.e. use dpkg-buildpackage without -B.

--no-source
Don't build source package, i.e. use dpkg-buildpackage with -B. This option is the
opposite of --source.

--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.

--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.

-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.

--binNMU=NMU-version
The version number of the binary NMU. This should be used in conjunction with
--make-binNMU. version is a single number for the (+bn) format used for binary
NMUs.

--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).

--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.

--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.

--run-lintian
Run lintian after a successful build.

--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.

--lintian-opt=options
Run lintian with the specified options.

--lintian-opts=options
Append extra options to existing options passed to lintian.

--run-piuparts
Run piuparts after a successful build.

--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.

--piuparts-opt=options
Run piuparts with the specified options.

--piuparts-opts=options
Append extra options to existing options passed to piuparts.

--piuparts-root-arg=options
Add an argument that is used to launch piuparts as root. If no arguments are
specified, piuparts will be launched via sudo.

--piuparts-root-args=options
Add arguments that are used to launch piuparts as root. If no arguments are
specified, piuparts will be launched via sudo.

--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 as root outside of the chroot. This option can be
used multiple times to add multiple commands. See the section EXTERNAL COMMANDS 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. See the section
EXTERNAL COMMANDS 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.
See the section EXTERNAL COMMANDS 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 (non-root) user running
sbuild inside the chroot. This option can be used multiple times to add multiple
commands. See the section EXTERNAL COMMANDS for more information.

--finished-build-commands=string
Run these commands immediately after the timed package build finishes. The command
is run as the (non-root) user running sbuild inside the chroot. This option can be
used multiple times to add multiple commands. See the section EXTERNAL COMMANDS 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 (non-root) user
running %sbuild inside the chroot. This option can be used multiple times to add
multiple commands. See the section EXTERNAL COMMANDS 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. See the section EXTERNAL COMMANDS for more
information.

--post-build-commands=string
Run this command after a successful build. The command is run as root outside of
the chroot. This option can be used multiple times to add multiple commands. See
the section EXTERNAL COMMANDS 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. See the section EXTERNAL COMMANDS for more information.

--log-external-command-output
Write output from external commands to the build log.

--log-external-command-error
Write error output from external commands to the build log.

--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.

--build-dep-resolver=resolver
Use the specified resolver to handle selecting the build dependencies. Supported
resolvers are apt (the default), aptitude, aspcud and xapt. 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 and other issues (bug #139615), 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 SAT solver, for a solution to the installation
problem. Since aspcud is a real SAT solver it will always find a solution if one
exists. 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.

--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.

--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.

--extra-package=package.deb
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 depenencies, 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.

--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://httpredir.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))

--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.

--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. Notice that the sbuild user in the chroot must have permissions
to create the path. Common writable locations are subdirectories of /tmp or /build.
The buildpath must be an empty directory because the last component of the path
will be removed after the build is finished. If you are running multiple sbuild
instances with the same build path in parallel for the same package, make sure that
your build path is not in a directory commonly mounted by all sbuild instances
(like /tmp or /home). In that case, use for example /build instead. Otherwise, your
builds will probably fail or contain wrong content.

--sbuild-mode=mode
Behaviour changes for use in a buildd environment. This overrides the $sbuild_mode
configuration 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. The pre/post-build- commands are run external to the
chroot. The chroot-setup/cleanup- commands and Starting/Finished-Build- commands are run
inside the chroot. They are all run as root except the Starting/Finishing-build- commands,
which are run as the current sbuild user. build-deps-failed runs similarly to
chroot-setup: in the chroot as root. build-failed runs similarly to finished-build: in the
chroot as the user.

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 remaining
columns show the percent escapes that are defined in each command. Percent escapes that
are available in all commands (%%, %d, %a, %b, %p, %s) are omitted.

command/action root chroot %c %r
──────────────────────────────────────────────────────────────────
Initialise chroot session
--pre-build-commands yes outside no yes
Setup the chroot and variables
--chroot-setup-commands yes inside no no
Update and upgrade packages
Install Dependencies
--build-deps-failed-commands yes inside no no
--starting-build-commands no inside no no
Run dpkg-buildpackage
--build-failed-commands no inside no no
--finished-build-commands no inside no no
Run lintian (if configured)
Cleanup build files and dependencies
--chroot-cleanup-commands yes inside yes no
Close schroot session
Run piuparts (if configured)
--post-build-commands yes outside 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 variable is only set after the build is finished, i.e in
--chroot-cleanup-commands and --post-build-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).

%r, %SBUILD_CHROOT_DIR
These escapes are converted to the absolute path on the host to the root directory
of the chroot. This variable is not set if the external command is run inside the
chroot. Thus this escape is only available for --pre-build-commands and
--post-build-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

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 %r. 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.

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 '%s'

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.

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.

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.

Use sbuild online using onworks.net services