emdebian-tools is a collection of scripts to ease cross-building Debian packages for Emdebian, reducing package size, separating translations into individual tdeb packages and handling dependencies. Includes support for installing cross building toolchains and building custom toolchains, automated patching of Debian packages to suit Emdebian needs, preparing root filesystems for Emdebian or specific machines and variants and cross building Debian packages inside or outside a chroot.
See also: The General Introduction to crossbuilding Debian on the Emdebian website.
emdebian-tools makes two changes to the apt configuration of your Debian installation to cross-build successfully. The first is to allow apt to use the Emdebian toolchain repository, the second is to ensure that apt can provide useful cross-building information to emdebian-tools during cross-build operations by ensuring that you have at least one apt source that is a primary Debian mirror. See 'FILES' for more information. These changes are reverted if the emdebian-tools package is purged.
Interim bug fix releases of emdebian-tools and other packages
like apt-cross are regularly made to the Emdebian
repository and updates are available alongside the toolchains. Generally,
version x.x.0 is uploaded to Debian and
allowed to migrate into Debian testing.
Versions x.x.x are uploaded to Emdebian
whilst waiting for the migration. Sometimes, the Debian package needs an
update, hence the version of emdebian-tools in
Debian Lenny is 1.4.3. During a release
freeze, it is not uncommon for many interim releases to be made to
Emdebian so that the packages can be as close as possible to the latest
subversion code. Check the latest version of emdebian-tools via the
toolchain repository data on the Emdebian website
It is possible that emdebian-tools 1.5.0 will
be backportable to Lenny but you should consider carefully whether it
would be better to build packages on the 'testing' or 'unstable' versions
of Debian.
For these reasons, it is important to update your apt or aptitude cache data after installing emdebian-tools and then upgrade your installation.
$ sudo apt-get update
$ sudo apt-get upgrade
Note that the dependencies of emdebian-tools will continue to change as the toolset develops and new packages are often added to the list built from the emdebian-tools source, so you will need to regularly add new packages when updating emdebian-tools and it is better to use:
$ sudo apt-get update
$ sudo apt-get dist-upgrade
emdebian-tools includes a set of scripts to aid building stripped down packages for Emdebian.
Emdebian aims to make Debian GNU/Linux a mainstream choice for embedded projects. The 'embedded' hardware can be anything from a full-blown PC to a MMU-less thing with a few MB of RAM and flash. There is not one solution that suits all of these scenarios at once, so Emdebian provides infrastructure and tools to produce systems according to particular project needs.
The aim of the project is to provide: minimised Debian packages, with the same sort of consistency that Debian itself offers, but a much smaller footprint, a complete Debian-based environment in which to build and customise them and complete distributions for various devices or types of devices.
The emdebian-tools implement one of the methods of preparing packages suitable for embedded devices, called the composite method, reliant on an emdebian version suffix: 'emN' : the 'em' prefix and a sequential digit.
In common with Debian versioning itself, the emdebian version resets to 1 each time a new package is available. Emdebian considers Debian as upstream so a new Debian version is still a new package as far as emdebian is concerned.
The suffix separates the emdebian archive files from other Debian archives and associated files being built from the same source tree on the developer system and identifies the archive as an adapted, stripped out, archive that is not necessarily compatible with any other .deb or .udeb files or programs. The method allows emdebian developers to have a version number that is independent of the full Debian version string.
Each tool supports multiple -v|--verbose
options (to a maximum of three levels) to describe each stage of the process.
Passing -v|--verbose to one tool also passes
the same level of verbosity to each emdebian-tool called by the original script.
Where possible, other programs called by emdebian-tools are also called with
suitable --verbose or --quiet options. If a particular stage is being
insufficiently verbose or quiet and the program concerned does support a
--verbose or --quiet option, please file a wishlist bug against
emdebian-tools. New users of emdebian-tools are advised to use
at least one --verbose
option to each emdebian-tools script.
Cross-building with emdebian-tools involves preventing certain
architecture-specific elements of a normal build from running on the host when
compiled for the target architecture. Other methods use emulators or native
environments but these are often limited to specific architecture combinations.
During ./configure, macros like AC_TRY_*
therefore need to be passed cached values using an
architecture-specific cache file. Values for the cache file should be obtained from
the Debian native buildd logs. em_make patches
debian/rules to omit make check which
would also attempt to run cross-built programs on the host architecture. Creating
$arch.cache files needs to be done by hand - each time the build fails during
configure.
Emdebian is an offical subproject of Debian.
emdebian-tools only began development after the
Etch release and various toolchain packages only included the required patches
after Etch was frozen. In addition, emdebian-tools is
in rapid development and updates are frequent. For these reasons,
it is not adviseable to use emdebian-tools on Etch
and difficulties can arise in Debian testing. Before filing bug reports, it is
worth checking if the bug still appears in a sid chroot. If empdebuild
fails, use a normal Debian debootstrap, login and change the sources to unstable.
Install emdebian-tools, update the apt cache, upgrade to the latest interim release
in Emdebian and then retest.
In line with normal Debian processes, Emdebian expects packages to be built against unstable and later migrate into testing prior to a (currently untested) method of migration into stable. Whilst it is possible to create packages against testing or even stable, this is the exception - just as in Debian.
Problems are also likely on Ubuntu and other Debian derivatives, although the reason is a little more complex. In order to calculate the versions of certain tools and dependencies, apt-cross and emdebian-tools need to be able to retrieve apt cache data of the native builds of those packages in Debian. Source versions are insufficient (the package may fail to build from source on the necessary architecture which makes it pointless to try and cross-build that version) and non-Debian release codenames are almost impossible to keep in sync with versions of packages in Debian itself. Just adding a Debian apt source could easily lead to dependency hell where multiple cross packages fail to install or upgrade due to conflicts with the underlying host system.
If in doubt, use a sid chroot on top of whatever suite or derivative that you normally use.
See Debian bug #492374 for updates on the status of building Crush natively as there are a series of problems with the current process that hinder native builds. See also Extending Emdebian on the Emdebian website. Many of the fixes needed for native build support need to made after the Lenny release.
Although emdebian-tools 1.4.3 is included in
Debian Lenny, there have been large changes since that version and various
parts of emdebian-tools may now be incompatible with
the version in Lenny. This is inevitable as the builds need to continue
tracking Debian unstable. The area of biggest change is going to be in the
building of packages for Emdebian Crush - the patches will have to be
continually updated for the version in unstable and as bugs are fixed in
unstable, the patches will get further and further out of sync with the
versions of those packages in Lenny. None of the packages in Lenny will
cross-build without patches so it will be very difficult to do actual
development for Crush on Lenny and things will only get worse as unstable
progresses towards the release of Debian 6.0 "Squeeze".
Nevertheless, emdebian-tools in Lenny can still
be used to prepare a cross-building chroot of Debian unstable which can
be kept up to date with Debian unstable and which will therefore be
able to successfully apply the patches from Emdebian SVN to the
corresponding packages from Debian unstable.
It is also expected that emdebian-tools
in Lenny should be able to provide toolchains and prepare root
filesystems and debootstrap chroots for Crush and Grip. If these stop
working, please file bugs against emdebian-tools.
dpkg-cross supports setting a default
cross-building architecture via debconf. emdebian-tools
makes extensive use of this default. To prevent tedious repetition of
--arch ARCH options, it is recommended that
dpkg-cross is configured to specify a default architecture.
The default can be system-wide:
$ sudo dpkg-reconfigure dpkg-cross
or user-specific:
$ cp /etc/dpkg-cross/cross-compile ~/.dpkg-cross/ $ editor ~/.dpkg-cross/cross-compile
emdebian-tools also supports defaults that can be set via debconf with overrides for individual users:
$ sudo dpkg-reconfigure emdebian-tools
or user-specific:
$ cp /etc/emsource.conf ~/.dpkg-cross/emsource $ editor ~/.dpkg-cross/emsource
dpkg-cross v1.32 and earlier contained some syntax errors relating
to unitialised values in Debian::DpkgCross. If
emdebian-tools is used with dpkg-cross v1.32 or
earlier (Etch has v1.32), perl will output some nuisance messages with
each operation. These are harmless and do not affect operation of
emdebian-tools.
emsetup - Checks your system for cross-build support and determines some defaults for other emdebian-tools scripts. Run this first, using the simulate option to see what changes may be needed.
emchain - Toolchain builder for cross compiling. If a pre-built toolchain is not found or not available, emchain can build a custom toolchain for your needs using the current Debian version of gcc. Using older versions of gcc is unsupported by emchain; packages built using toolchains based on old versions of gcc should not be uploaded to the Emdebian target repository.
emsource - wrapper for
apt-get source that adds support for emdebian patches
held in SVN. If you have an Emdebian SVN username, changes to the emdebian
patches can be committed back to Emdebian. emsource
checks for an existing emdebianised source tree and runs
em_make where appropriate. emsource is
an optional component of emdebian-tools. If the package does not need to have patches in Emdebian SVN, apt-get source or dget -x can be used instead. (Remember to run em_make on the new Debian source if you do not use emsource.)
em_make - similar to dh_make for Debian,
em_make makes an Emdebian package from a Debian source
tree - beginning the process of emdebianisation. It strips out all
documentation and udeb packages. Upstream files (including debian/* files) are
used as the basis of patches for emdebian. debian/rules is
a special case as it has to be patched prior to running any other
dpkg-* commands or executing debian/rules
itself. em_make prepares suitable patches that are maintained
and updated by emdebuild.
emlocale has been replaced by em_installtdeb
which operates without $pkg-locale-$lang files and
emdebian-$pkg-locale patch files and without
changes to debian/control. em_installtdeb
runs at the end of the build (acting as a second build if the first completes
successfully) and the results of the em_installtdeb run are checked
with the same emdebuild build checks as before. This provides a second
.changes file, a second .dsc file and a stripped
down .tdeb.tar.gz tarball containing (hopefully) enough files for
translators to prepare independent tdeb uploads. Emdebian has support
for the necessary locale repository and the tdeb
.changes file must NOT be uploaded
to the normal Emdebian target repository, neither should tdeb files
be uploaded to Debian at this time. See em_installtdeb (1).
emdebuild - a wrapper script for
dpkg-buildpackage using -a to specify the
target architecture and -uc -us -rfakeroot -D as well as using
the nodocs nochecks noudeb DEB_BUILD_OPTIONS. If this
is the first release of an emdebian version of the package,
-sa is added automatically to include the original source
into the .changes file. Provided that the .orig.tar.gz has not been modified,
it is safe to ignore warnings about multiple uploads of the .tar.gz.
emdebian-tools manages two configuration files:
/etc/emsource.conf : Contains the debconf
values for your Emdebian SVN username (if any) and Emdebian working directory
(if any) for new source downloads. Also contains the debconf boolean value
'aptagent' that indicates whether toolchains should be installed using
apt-get (true) or aptitude (false).
Values from emsource.conf can also be set
locally on a per-user basis by copying /etc/emsource.conf
to ~/.dpkg-cross/emsource and editing the values.
These settings will override any values in /etc/emsource.conf
and will not be modified by emdebian-tools.
Installation changes
/etc/apt/sources.list.d/emdebian.sources.list: Provides the apt source for the Emdebian toolchain repository so that your cross-building toolchains can be installed and updated automatically.emdebian-tools also needs to be able to query apt cache data from a Debian mirror that supports all cross-building architectures - these repositories are called 'primary mirrors' in Debian. If
/etc/apt/sources.listdoes not contain a primary Debian mirror, this file will include the default primary mirror for emdebian-tools:ftp.uk.debian.org. If you prefer to use a closer or faster primary mirror, please refer to the Debian Mirror List http://www.debian.org/mirror/list and add your preferred primary mirror to/etc/apt/sources.list, run 'apt-get update', then use 'dpkg-reconfigure emdebian-tools' to update/etc/apt/sources.list.d/emdebian.sources.list. At least one primary mirror, as defined on the DML page, must be available to use emdebian-tools.It is not possible to set repositories on a per-user basis.
emdebian-tools uses the specified Emdebian working directory
for emsource, empdebuild and
emsandbox. chroot and rootfs tarballs are created in $WORK and the
value of $WORK itself is set in /etc/emsource.conf using debconf.
If $WORK represents your Emdebian working directory, emdebian-tools
uses this subdirectory hierarchy:
$WORK/machine/
Contains machine specific configuration data used by emsandbox and emsource.
$WORK/machine/$MACHINE
One directory for each type of machine. $MACHINE represents the machine name.
$WORK/machine/$MACHINE/$VARIANT
One directory for each variant of each type of machine. Variant is the variant name. If none is specified,
$WORK/machine/$MACHINE/defaultis used.
$WORK/pbuilder/
Top level directory for empdebuild.
aptcache
Cached packages for cross-building emdebianised packages in a build chroot. Note that this directory will contain packages from your host architecture and packages for your target architecture(s) that were needed as cross dependencies for other builds and downloaded by apt-cross.
result
Contains a further tree holding the .changes, .dsc, .tar.gz, .build, emdebian patch files and the cross built .deb package files for all successful builds. Subdirectories are organised by package name initial letter, then package name and 'trunk' (which belies the history of the build as based in a subversion hierarchy).
build
Should be empty. empdebuild unpacks the cross-building chroot into this directory, using the process ID of empdebuild as the name of a new subdirectory. Any subdirectories left in
build/can be deleted once the build completes successfully.
trunk
The top level of the emsource build area. Subdirectories are organised by package name initial letter, then package name and 'trunk' - branches and tags may also be present but are usually unused.
If you also have a SVN checkout of the main Emdebian repository, you may end up duplicating the emsource part of the hierarchy. In such situations, remember that emsource knows which hierarchy is your $WORK, even if you forget.
apt-cross also creates apt cache data used by emdebian-tools
and this is typically stored in ~/.apt-cross/.
emdebian-tools support colourised output to supporting
terminals using Text::ANSIColor. This can be disabled by setting the environment
variable ANSI_COLORS_DISABLED. In general, colour is used when
the scripts are called in verbose mode or when performing actions that may be
unfamiliar to new users of the package. Blue indicates a general status message
from the script itself. Green indicates that the script has modified a file or
performed an action that modifies data external to the current process -
e.g. adding a file to Emdebian SVN. Red indicates errors. Programs and
scripts called by emdebian-tools are left to output
their own colours or simply output to the terminal default. Colours are
implemented via escape sequences and do not affect copying textual output from
the terminal into other applications.
The emdebian-tools scripts were written
by Neil Williams <codehelp@debian.org>.
This manual page was written by Neil Williams
<codehelp@debian.org>
apt-cross (1), dpkg-cross (1), em_make (1), em_installtdeb (1), emchain (1), emsource (1), emdebuild (1), emsetup (1), emsandbox (1).
WWW versions of these manpages: http://linux.codehelp.co.uk/emdebian/man/