NAME
xdeb - build a set of Debian packages
SYNOPSIS
xdeb [-C file] [-a architecture] [-b builddir] [-d destdir]
[--apt-source] [--prefer-apt] [--only-explicit] [-f] [--debug]
[--no-clean-after] [--no-lintian] [--sequence] [--list-builds]
[--all] [-x package] [--no-native-import] package [...]
xdeb --convert [-C file] [-a architecture] [--no-convert-install]
package.deb [...]
DESCRIPTION
Traditionally, Debian-format packages (as used in Debian, Ubuntu, and so
on) have been built from source code by uploading source to central build
servers, which then upload binaries to an archive. While it is possible
for developers to build packages locally, and indeed in Debian it is the
norm for developers to upload binaries for at least one architecture
along with the source package, they do not usually build the whole system
from scratch this way.
Debian-format packages are also normally compiled on their native
architecture. This is not an intrinsic limitation of the tools, but a
reflection of the fact that many upstream packages cannot be cross-
compiled without human care and attention, which is a scarcer resource
than computer time.
However, on some architectures, fast hardware suitable for build daemons
may be difficult to come by. This changes the economics of cross-
building, so that it is worth spending that extra human attention on it.
xdeb takes a set of target package names or names of directories
containing packages, and builds those packages for the specified
architecture (or for the native architecture if unspecified), in an
appropriate sequence. As builds complete, it will install packages
necessary to satisfy build-dependencies for subsequent stages (TODO not
yet implemented). When necessary, it will convert foreign-architecture
binary packages to packages that can be installed safely on the native
architecture without conflicts. When cross-compiling, it checks to
ensure that programs were not accidentally built to run on the native
architecture, which is a common failure mode.
For the time being, xdeb fetches source code using apt-get(8). This is
expected to become optional rather than the default.
OPTIONS
-C, --config-file file
Read file as an additional configuration file.
-a, --architecture architecture
Build packages for architecture rather than for the native
architecture. Configuration file option: architecture.
-b, --build-directory builddir
Build packages in builddir rather than in the current directory.
This option may be given multiple times; in that case, the first
builddir will be used for packages fetched using apt-get and as the
default destination directory, but otherwise all supplied
directories will be scanned for packages and treated equivalently.
Configuration file option: builddirs.
-d, --dest-directory destdir
Leave successfully built packages in destdir rather than in the
first build directory. Configuration file option: destdir.
--apt-source
Fetch source code using apt-get. If this is not specified, then
only packages in any builddir will be built, and only those
packages will be used to expand dependencies for build sequencing.
Configuration file option: apt_source.
--prefer-apt
Prefer source packages available using apt-get, even if an older
version of the package is already available in the build directory.
This option implies --apt-source. Configuration file option:
prefer_apt.
--only-explicit
Only build packages explicitly listed on the command line. For all
other packages, import native builds rather than attempting to
cross-compile them. This may produce less complete builds in some
cases, but if the native repository is reasonably complete then it
greatly reduces the number of builds that need to be run and it
avoids many problems with build-dependency loops.
-f, --force-rebuild
Rebuild packages even if the source code appears to be unchanged.
xdeb relies on the version number in debian/changelog to detect
changes. Configuration file option: force_rebuild.
--debug
Emit extra messages useful for debugging build sequencing.
Configuration file option: debug.
--parallel
Use as many jobs as there are CPUs on the system. Configuration
file option: parallel.
--no-clean-after
Do not clean each source tree after building.
--no-lintian
Do not run lintian(1) to check whether cross-compiled packages were
built for the requested architecture. This can speed up builds
when you are sure that all packages are cross-safe, but is
otherwise not recommended. Configuration file option: lintian
(defaults to true).
--sequence
Just show the build sequence, but don't actually build anything.
Only packages whose names are suffixed with '*' will be built; the
rest are listed for information only. Configuration file option:
sequence.
--list-builds
List all current successful builds for the selected architecture in
the build directory. Configuration file option: list_builds.
--all
Build all packages in the working tree. Configuration file option:
all.
-x, --exclude package
Exclude package from the list of packages computed by --all. It
will only be built if required to satisfy dependencies.
Configuration file option: exclude.
--no-native-import
Normally, xdeb will import native builds of certain packages rather
than attempting to cross-build them. This option disables that
behaviour. Use this when working on fixing cross-builds of the
packages in question.
--convert
Rather than building, convert a set of foreign-architecture binary
packages to packages that can be installed safely on the native
architecture without conflicts, as though they had just been built
by xdeb. This silently ignores any packages that cannot usefully
be converted.
--no-convert-install
Normally, xdeb --convert will install packages after converting
them for use on the native architecture. This option suppresses
that behaviour.
FILES
/etc/xdeb/xdeb.cfg
Site-wide configuration file. xdeb will also look for xdeb.cfg in
the directory alongside its own executable, to support running from
its own build directory.
.xdeb, xdeb.cfg
Read from the current directory as a per-project configuration
file. You may supply additional configuration files using the -C
option.
CONFIGURATION FILE
The configuration file is a ConfigParser-format (a.k.a. "INI file") file.
Recognised sections are Lists and Options. The Lists section lists
specific packages that are exceptions from various built-in rules; see
the supplied site-wide configuration file for examples. The Options
section may be used to provide defaults for any values not explicitly set
on the command line.
It is also possible to have a xdeb.cfg configuration file in a directory
containing an individual package. Such configuration files may include a
Package section, with the following optional keys:
directory
Relative path to the directory that really contains the package's
files. This directory will need to contain a debian subdirectory
in order to build properly (which may be created due to another
option in this section). This option is useful when package files
are fetched from another repository, and some extra work is needed
to put the debian subdirectory in place.
debian_symlink
Create debian as a symbolic link to the value of this option.
ADVICE ON OPERATION
Generally speaking, you can re-run xdeb on failures and it will start
again with the last package it tried to build. If the first builddir and
destdir are the same, then xdeb will not notice that a package had not
been successfully built in a previous run if it contained objects for the
wrong architecture, or if it failed to run dpkg-cross or dpkg -i. In
this case, you may need to remove the .changes file for that package
before trying again. We recommend that destdir be set to a directory
which is not a build directory.
AUTHORS
xdeb was originally written by Colin Watson <cjwatson@canonical.com> for
Chromium OS, and then renamed to xdeb for more general use.
xdeb is copyright (C) 2009, 2010 The Chromium OS Authors, (C) 2010
Canonical Ltd.