This wiki page is intended to describe the issues of, and mechanisms for, bootstrapping Debian from zero to a full archive. Otherwise known as profile builds (and previously staged builds). It has developed somewhat over several years as practical experience has grown, and is now technically useable, and making its way into the archive.

The detailed spec is at BuildProfileSpec


There is a real need to bootstrap Debian from sources when doing new ports or flavours (sub-arch builds). Every new architecture or optimisation flavour needs to do this at least once, and making it easier than the current 'really very hard' would be great. It is also very useful for cross-compiling to new or non-self-hosted architectures, and for a genuinely new arch at least part of the system (toolchains+build-essential) has to be cross-built until there is enough to become self-hosting.

New bootstraps are done every year. At the time of writing sh4, armhf, uclibc and avr32, and x32 have been done, and arm64 and mips64el are in progress. Subarch flavoured rebuilds (e.g. to optimise for a particular CPU) are particularly useful on ARM and MIPS architectures (Raspberry Pi is most popular recent example).

This is also helpful when bringing a lagged architecture up to date, especially considering documentation tools (that may be too old), optional dependencies (that may be too old or not exist) like php5, which depends on everything and the kitchen sink, etc. I wish this had been implemented when starting to work on m68k…

It can also help to solve problems like libc ABI changes by rebuilding everything. Example: (But this was solved by upstream reverting the change in the end)

Currently people tend to use non-debian tools (such as Yocto/Gentoo/OpenEmbedded) to get a basic rootfs image of the target arch/ABI then do native building within that. This works but needs a great deal of manual loop-breaking and we really ought to be able to bootstrap our own OS.

Putting the necessary bootstrapping metadata and build rules into the packages themselves in an orderly fashion enables the info to be maintained easily. QA tests to report on breakage will help enormously here. It also makes for a repeatable and deterministic process.

This work needs build-system and policy changes, which are detailed on this page.

The goal is to be able to run regular automated bootstrap builds of the archive to check that it works, and allow porters to concentrate on actual porting work, rather than a lot of associated aggravation.


The current (Jan 2014) status is:

Packaging/Design principles

An important principle in the design is that the packaging changes necessary for this to work are reasonably clear and transparent. A Debian packager should not have to understand this stuff (staged builds and cross-building) in loving detail to avoid breaking things whilst making maintenance changes.

All the metadata needed should be part of the packages, so it can be maintained over time. Any solution with external patches/metadata is doomed to bitrot.

These principles informed the design when deciding between different technically-satisfactory ways of achieving things.


The concept is simple: add support for minimal/reduced/staged builds to packages involved in build-dependency loops, so that build loops are broken. Also ensure packages cross-build properly so that an initial minimal native-building system can be produced.

Working out which packages to modify, and how, is fundamentally a manual process, done by manually examining build-dep loops and choosing which packages are most easily and cleanly modified. Since the "Port bootstrap build-ordering tool" project in the GSoC 2012, the process of finding source packages which make sense to modify can be semi-automated. Once that is done, building bootstrap-able packages can be a fully automated process.

This spec caters for multiple stages of staged/bootstrap build, so that if necessary a package can be built with reducing build profiles before the final, normal build.

The reduced dependencies are specified in the control file, using a concept which is called build profiles. The build profile format was proposed by Guillem Jover together with other solutions he presented in bug#661538. Build profiles extend the Build-Depends format with a syntax similar to architecture restrictions but using < and > instead. The current Spec is detailed in BuildProfileSpec. Previous revisions were discussed on debian-devel and debian-dpkg.

Build-Depends: huge (>= 1.0) [i386 arm] <!cross !pkg.somepkg.nosomefeature>, tiny

The build dependency "huge" would not be required by the source package if it is built in the "cross" or "pkg.somepkg.nosomefeature" profile. This mechanism neatly allows for removed build-deps, replaced build-deps and added build-deps, and an arbitrary number of possible 'profiles'.

Besides bootstrapping, these build profiles can also be used for embedded builds, to allow for changed build-deps when cross-building, and build-dependencies only needed for running tests.

This scheme supersedes an earlier version, (referred-to as 'staged' builds), which used repeated Build-depends-StageN: lines. See the dpkg bug#661538 for the evolution of this. The profile labels are arbitrary but agreement on label usage is necessary. The profile namespace is defined in the BuildProfileSpec.

An environment variable (DEB_BUILD_PROFILES) is used to control when packages are built in reduced staged/bootstrap mode, and at what stage.. debian/rules can check this variable and miss out some optional features to reduce the dependency tree (e.g. building kerberos without LDAP support, avahi without gtk and qt, etc). dpkg-buildpackage/dpkg-checkbuilddeps also checks the reduced/changed build-dependencies instead of the normal ones.

DEB_BUILD_PROFILES is used because it is preserved and passed on by all build tools, and this is a build option like other things it is used to control.

So setting DEB_BUILD_PROFILES=cross will cause dpkg-buildpackage to call dpkg-checkbuilddeps with -Pcross so that cross build dependencies are checked, rather than the normal set.

Bootstrapped/Staged packages are marked as such (in the changes file) with a new field called Built-for-profiles:. They are not uploaded to normal repositories. It is important to avoid accidentally mistaking a bootstrap/staged package for a 'real' (normally-built) package. As soon as possible a bootstrap package should be rebuilt as a full package, to avoid having to rebuild many packages against the full version once it is available. A version suffix is no longer useful, because the .buildinfo file tracks the profiles used for building. A version suffix would break reproducibility.


This process is usually called 'profile' builds, but the terms 'staged' builds and 'bootstrap' builds have also been used as it developed.

Available Patches

Patches are tracked on BuildProfileSpec

The dpkg bug gives a useful idea of how this spec has developed.

Here are various older patches for packages, adding support for profiled builds of packages:


Bootstrapping is closely related to support for cross-building Debian packages because at least part of the process must be done cross. Enough packages to make a bootable image need to be cross-buildable, because you cannot magic a system out of thin air. To move from cross to native building you need build-essential to be cross-buildable.

The number of build-loops that must be broken for cross-building is much smaller than the number that need to be broken for native building. This spec proposes that we start by fixing the loops that mean you can't even cross-build a base Debian image before going on to fix all the packages which have native build-dep loops.

Debian/Ubuntu cross-building is documented here:

Patched sources with build-profile patches applied and extra multiarch and profile build support in package metadata are in

For cross-building to be reliable cross-dependency metadata needs to be in packages, so that it is clear whether a build dependency should be satisfied by the build architecture or the host architecture. Multiarch information can be used to provide this information along with build-dependency decoration for the fairly rare exceptions. Details are specified here: MultiarchCross

The current state of buildability using this technology is recorded here: and

Prior to useful amounts of multiarch metadata is in packages, heurisitics must be used, as implemented in xdeb (and the now-deprecated apt-cross), or all dependencies must be installed for both host and native, as implemented in xapt. These are all ugly and horrid, but better than nothing. xdeb or xapt are better than multiarch-cross in wheezy and precise, but multiarch-cross is where all the current work is, and as of end 2012 it works for much of the base system in Debian unstable and Ubuntu raring. From Maverick and Jessie onwards multiarch cross-building is the recommended method.

Automated Bootstrapping

The full automated bootstrapping process needs to keep track of staged builds and rebuilding things as needed so that they don't hang around any longer than necessary. However any such tool could get out of sync with the current status, unless it is always determinable from the current package-set state. This spec attempts to define things such that it is always intrinsically stateful.

Packages do need to be uploaded to a bootstrap repository in order to satisfy build-dependecies (that's the whole point). However because packages of the same version get built, and thus uploaded, more than once we need a way to deal with this. One proposal is to append ~stageN+M to the package version automatically, where N is the stage number and M a continuously incremented (by the buildd) number. Or do binNMUs, which are already recognised by the tools and package management system very well, and almost all packages are (supposedly) binNMU safe. This was awkward when combined with multiarch until the separate binNMU changelog feature was implemented.

See 'Changed binary packages' below for a discussion of how profiles causing a binary package normally built to be omitted should be dealt with. The meta-data in package Build-Deps allows static analysis tools to determine in advance if the package set has a fully linearisable build-order or not. The botch tool can do this analysis.

Heuristics to detect bootstrapping problems

Ideally the following would be converted into a tool that detects and reports this problems, so that maintainers can fix them. These would be shown on a site such as the PTS or


This section collects some information about how this concept has developed over time in order to make the above page clearer.

The initial proposal was written down in 2010 as a result of a UDS (ubuntu Developer Summit) discussion: Specs/M/ARMAutomatedBootstrap Back then the concept was called 'Staged Builds', and used a simple extra line in the control file repeating and modifying the normal build-dependencies: Build-Depends-StageN and builds controlled with DEB_BUILD_OPTIONS=profile=stage1

This made it very easy to implement as existing tools will not barf as no new syntax is used. However it is an ugly implementation inside dpkg with many extra fields defined and a limit (of 2) on how many stages could be supported. No other profiles types are possible without hard-defining more fields inside dpkg. See 661538 for how that developed.

3 successive years of GSOC projects by Gustavo Alkmim, P. J McDermott, Johannes Schauer, and Thibaut Girka, progressed the practical and theoretical work, as well as heavy sponsorship of this work by Linaro and Canonical which enabled a lot of the supporting cross-building and multiarch work to get done.

It became clear from actually doing staged builds that it made more sense if cross-building, test-skipping, doc-skipping and language/tool extra dependencies (bootstrapping) changes were described independently rather than arbitrarily lumped together in the way a bootstrap on a particular arch might like it. So the newer profile modifier syntax was developed and implemented, whilst being tested on actual cross-builds and bootstraps.

Over 2013 an actual spec and implementation in dpkg was pinned down, agreed and implemented, leading to a profile-supporting dpkg upload at the end of 2013.

These are some related activities and documents which have generated input for this one.



Thanks to Jonathan Austin, Steve McIntyre, Steve Langasek, Loic Minier, P. J. McDermott, and Johannes Schauer for helping clarify the thoughts described above.

CategoryEmdebian | CategoryDeveloper