.\" xdeb.1
.Dd October 15, 2009
.Os Linaro
.ds volume-operating-system Linaro
.Dt XDEB 1
.Sh NAME
.Nm xdeb
.Nd build a set of Debian packages
.Sh SYNOPSIS
.Nm
.Op Fl C Ar file
.Op Fl a Ar architecture
.Op Fl b Ar builddir
.Op Fl d Ar destdir
.Op Fl Fl apt\-source
.Op Fl Fl prefer\-apt
.Op Fl Fl only\-explicit
.Op Fl f
.Op Fl Fl debug
.Op Fl Fl generate-graph
.Op Fl Fl generate-compact-graph
.Op Fl Fl no\-clean\-after
.Op Fl Fl no\-lintian
.Op Fl Fl sequence
.Op Fl Fl list\-builds
.Op Fl Fl all
.Op Fl x Ar package
.Op Fl Fl no\-native\-import
.Ar package Op \&...
.br
.Nm
.Fl Fl convert
.Op Fl C Ar file
.Op Fl a Ar architecture
.Op Fl Fl no\-convert\-install
.Ar package Ns Li \&.deb Op \&...
.Sh 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.
.Pp
.Nm
provides this functionality in a convenient form by providing 
build-ordering, cross-dependency satisfaction, and cross-building all in 
one tool.
.Pp
.Nm
takes a set of target package names or names of directories containing
packages, and builds those packages for the specified
.Ar 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.
.Pp
.Nm
fetches source code using
.Xr 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.
.Pp
e.g.
.br
deb [arch=armel] http://ports.ubuntu.com/ubuntu-ports maverick main universe
.br
deb-src http://ports.ubuntu.com/ubuntu-ports maverick main universe
.Pp
Multiple repositories can be specified and APT pinning and
release-default options used to provide preferred source repositories.
.Nm
will respect APT policy.
.Sh OPTIONS
.Bl -tag -width 4n
.It Xo Fl C ,
.Fl Fl config\-file Ar file
.Xc
Read
.Ar file
as an additional configuration file.
.It Xo Fl a ,
.Fl Fl architecture Ar architecture
.Xc
Build packages for
.Ar architecture
rather than for the native architecture.
Configuration file option:
.Li architecture .
.It Xo Fl b ,
.Fl Fl build\-directory Ar builddir
.Xc
Build packages in
.Ar builddir
rather than in the current directory.
This option may be given multiple times; in that case, the first
.Ar 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:
.Li builddirs .
.It Xo Fl d ,
.Fl Fl dest\-directory Ar destdir
.Xc
Leave successfully built packages in
.Ar destdir
rather than in the first build directory.
Configuration file option:
.Li destdir .
.It Fl Fl apt\-source
Fetch source code using apt\-get.
If this is not specified, then only packages in any
.Ar builddir
will be built, and only those packages will be used to expand dependencies
for build sequencing.
Configuration file option:
.Li apt_source .
.It Fl Fl 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
.Fl Fl apt\-source.
Configuration file option:
.Li prefer_apt .
.It Fl Fl 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.
.It Xo Fl f ,
.Fl Fl force\-rebuild
.Xc
Rebuild packages even if the source code appears to be unchanged.
.Nm
relies on the version number in
.Pa debian/changelog
to detect changes.
Configuration file option:
.Li force_rebuild .
.It Fl Fl debug
Emit extra messages useful for debugging build sequencing.
Configuration file option:
.Li debug .
.It Fl Fl generate-graph
Emit dot graph version of debug build dependency information.
See README-graph for further details.
Configuration file option:
.Li generate-graph .
.It Fl Fl 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:
.Li generate-compact-graph .
.It Fl Fl parallel
Use as many jobs as there are CPUs on the system.
Configuration file option:
.Li parallel .
.It Fl Fl no\-clean\-after
Do not clean each source tree after building.
.It Fl Fl no\-lintian
Do not run
.Xr 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
.Em not recommended .
Configuration file option:
.Li lintian
(defaults to true).
.It Fl Fl sequence
Just show the build sequence, but don't actually build anything.
Only packages whose names are suffixed with
.Sq *
will be built; the rest are listed for information only.
Configuration file option:
.Li sequence .
.It Fl Fl list\-builds
List all current successful builds for the selected
.Ar architecture
in the build directory.
Configuration file option:
.Li list_builds .
.It Fl Fl all
Build all packages in the working tree.
Configuration file option:
.Li all .
.It Xo Fl x ,
.Fl Fl exclude Ar package
.Xc
Exclude
.Ar package
from the list of packages computed by
.Fl Fl all .
It will only be built if required to satisfy dependencies.
Configuration file option:
.Li exclude .
.It Fl Fl no\-native\-import
Normally,
.Nm
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.
.It Fl Fl 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
.Nm .
This silently ignores any packages that cannot usefully be converted.
.It Fl Fl no\-convert\-install
Normally,
.Nm
.Fl Fl convert
will install packages after converting them for use on the native
architecture.
This option suppresses that behaviour.
.El
.Sh FILES
.Bl -tag -width 4n
.It Pa /etc/xdeb/xdeb.cfg
Site-wide configuration file.
.Nm
will also look for
.Pa xdeb.cfg
in the directory alongside its own executable, to support running from its
own build directory.
.It Pa .xdeb , Pa xdeb.cfg
Read from the current directory as a per-project configuration file.
You may supply additional configuration files using the
.Fl C
option.
.El
.Sh CONFIGURATION FILE
The configuration file is a ConfigParser-format (a.k.a. "INI file") file.
Recognised sections are
.Li Lists
and
.Li Options .
The
.Li Lists
section lists specific packages that are exceptions from various built-in
rules; see the supplied site-wide configuration file for examples.
The
.Li Options
section may be used to provide defaults for any values not explicitly set on
the command line.
.Pp
It is also possible to have a
.Pa xdeb.cfg
configuration file in a directory containing an individual package.
Such configuration files may include a
.Li Package
section, with the following optional keys:
.Bl -tag -width 4n
.It Li directory
Relative path to the directory that really contains the package's files.
This directory will need to contain a
.Pa 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
.Pa debian
subdirectory in place.
.It Li debian_symlink
Create
.Pa debian
as a symbolic link to the value of this option.
.El
.Sh ADVICE ON OPERATION
Generally speaking, you can re-run
.Nm
on failures and it will start again with the last package it tried to build.
If the first
.Ar builddir
and
.Ar destdir
are the same, then
.Nm
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
.Ic dpkg\-cross
or
.Ic dpkg Fl i .
In this case, you may need to remove the
.Pa .changes
file for that package before trying again.
We recommend that
.Ar destdir
be set to a directory which is not a build directory.
.Sh AUTHORS
.Nm
was originally written by
.An Colin Watson Aq cjwatson@canonical.com
for Chromium OS, and then renamed to
.Nm
for more general use.
.Pp
.An -nosplit
.Nm
is copyright \(co 2009, 2010
.An The Chromium OS Authors ,
\(co 2010
.An Canonical Ltd.