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] [--generate-graph] [--generate-compact-graph]
          [--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
     natively.  However it is often useful to be able to cross-build packages, and sometimes
     whole systems.

     xdeb provides this functionality in a convenient form by providing build-ordering, cross-
     dependency satisfaction, and cross-building all in one tool.

     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.  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 build architecture, which is a common
     failure mode.

     xdeb fetches source code using apt-get(8).  It defaults to using the build-system APT
     configuration, so you should ensure that a repository containing packages of the target
     architecture is specified on the relevant machine/chroot.

     e.g.
     deb [arch=armel] http://ports.ubuntu.com/ubuntu-ports maverick main universe
     deb-src http://ports.ubuntu.com/ubuntu-ports maverick main universe

     Multiple repositories can be specified and APT pinning and release-default options used to
     provide preferred source repositories.  xdeb will respect APT policy.

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.

     --generate-graph
           Emit dot graph version of debug build dependency information.  See README-graph for
           further details.  Configuration file option: generate-graph.

     --generate-compact-graph
           Emit dot graph version of debug build dependency information, but without the
           intermediate binary dependencies, in order to produce a more readable graph.  See
           README-graph for further details.  Configuration file option: generate-compact-graph.

     --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 © 2009, 2010 The Chromium OS Authors, © 2010 Canonical Ltd.