emdebian-tools(1)

NAME

emdebian-tools - Suite of tools to cross-build Debian packages for
Emdebian.

DESCRIPTION

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[1] to crossbuilding Debian on the Emdebian website.

INSTALLATION CHANGES

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.

For these reasons, it is important to update your apt or aptitude cache data after installing emdebian-tools and then upgrade your
installation. Interim bug fix releases of emdebian-tools are made to
the Emdebian repository and updates are available alongside the
toolchains.

$ sudo apt-get update
$ sudo apt-get upgrade

Note that the dependencies of emdebian-tools will continue to change as the toolset develops so sometimes you will need to add new packages and it can be better to use:

$ sudo apt-get update
$ sudo apt-get dist-upgrade

BACKGROUND

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.

Which suite?

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.

DEFAULTS

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 older than 1.33
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.

COMPONENTS

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
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.

FILES

emdebian-tools manages two configuration files:

1. /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).

Local settings
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.

2. 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.list does 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/default is 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/.

COLOUR

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.

AUTHOR

The emdebian-tools scripts were written by Neil Williams <codehelp@debian.org>.

This manual page was written by Neil Williams <codehelp@debian.org>

SEE ALSO

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/[3]

AUTHOR

Emdebian

Neil Williams

Author.

COPYRIGHT

NOTES

1. General Introduction

http://www.emdebian.org/emdebian/intro.html

2. http://www.debian.org/mirror/list

3. http://linux.codehelp.co.uk/emdebian/man/
http://linux.codehelp.co.uk/emdebian/man/

EMDEBIAN-TOOLS Thu 26 Jun 2008 18:11:15 BST EMDEBIAN-TOOLS(1)