--- name: "emdebian-tools" section: "1" platform: "linux" package: "emdebian-tools" version: "1.4.3" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/emdebian-tools" --- # emdebian-tools(1) Suite of tools to cross-build Debian packages for Emdebian. ## 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 \. This manual page was written by Neil Williams \ ## 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/