<?xml version="1.0" encoding="UTF-8"?>
<refentry id="emdebian-tools">
  <refentryinfo>
    <productname>emdebian-tools</productname>
    <productnumber/>
  </refentryinfo>
  <refmeta>
    <refentrytitle>emdebian-tools</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">EMDEBIAN-TOOLS</refmiscinfo>
    <refmiscinfo class="manual">EMDEBIAN-TOOLS</refmiscinfo>
  </refmeta>
  <refnamediv id="name">
    <refname>emdebian-tools</refname>
    <refpurpose>Suite of tools to cross-build Debian packages for Emdebian.</refpurpose>
  </refnamediv>
  <refsect1 id="description">
    <title>DESCRIPTION</title>
    <para><emphasis>emdebian-tools</emphasis> 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.
    </para>
    <para>See also: The <ulink url="http://www.emdebian.org/emdebian/intro.html">General Introduction</ulink>
    to crossbuilding Debian on the Emdebian website.
    </para>
    <refsect2 id="installation">
      <title>INSTALLATION CHANGES</title>
      <para><emphasis>emdebian-tools</emphasis> 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
      <emphasis>emdebian-tools</emphasis> 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
      <emphasis>emdebian-tools</emphasis> package is purged.
      </para>
      <para>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.
      </para>
      <programlisting>
$ sudo apt-get update
$ sudo apt-get upgrade
      </programlisting>
      <para>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:
      </para>
      <programlisting>
$ sudo apt-get update
$ sudo apt-get dist-upgrade
      </programlisting>
    </refsect2>
    <refsect2 id="background">
      <title>BACKGROUND</title>
      <para><emphasis>emdebian-tools</emphasis> includes a set of scripts to aid
          building stripped down packages for Emdebian.</para>
      <para>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.</para>
      <para>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.</para>
      <para>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.</para>
      <para>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.</para>
      <para>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.</para>
      <para>Each tool supports multiple <option>-v</option>|<option>--verbose</option>
          options (to a maximum of three levels) to describe each stage of the process.
          Passing <option>-v</option>|<option>--verbose</option> 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
          <emphasis role="bold">at least one</emphasis> <option>--verbose</option>
          option to each emdebian-tools script.
          </para>
      <para>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 <filename>./configure</filename>, macros like <emphasis>AC_TRY_*</emphasis>
      therefore need to be passed <emphasis>cached</emphasis> values using an
      architecture-specific cache file. Values for the cache file should be obtained from
      the Debian native buildd logs. <filename>em_make</filename> patches
      <filename>debian/rules</filename> to omit <emphasis>make check</emphasis> 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.
      </para>
      <para>Emdebian is an offical subproject of Debian.</para>
    </refsect2>
    <refsect2 id="suite">
      <title>Which suite?</title>
      <para><emphasis>emdebian-tools</emphasis> only began development after the
      Etch release and various toolchain packages only included the required patches
      after Etch was frozen. In addition, <emphasis>emdebian-tools</emphasis> is
      in rapid development and updates are frequent. For these reasons,
      it is not adviseable to use <emphasis>emdebian-tools</emphasis> 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 <filename>empdebuild</filename>
      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.
      </para>
      <para>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.
      </para>
      <para>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, <command>apt-cross</command>
     and <emphasis>emdebian-tools</emphasis> need to be able to retrieve apt
     cache data of the <emphasis role="bold">native</emphasis> 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.
     </para>
      <para>If in doubt, use a sid chroot on top of whatever suite or
    derivative that you normally use.
      </para>
    </refsect2>
    <refsect2 id="defaults">
      <title>DEFAULTS</title>
      <para><command>dpkg-cross</command> supports setting a default
          cross-building architecture via debconf. <emphasis>emdebian-tools</emphasis>
          makes extensive use of this default. To prevent tedious repetition of
          <option>--arch ARCH</option> options, it is recommended that
          <filename>dpkg-cross</filename> is configured to specify a default architecture.
          The default can be system-wide:
<programlisting>
$ sudo dpkg-reconfigure dpkg-cross
</programlisting>
          or user-specific:
<programlisting>
$ cp /etc/dpkg-cross/cross-compile ~/.dpkg-cross/
$ editor ~/.dpkg-cross/cross-compile
</programlisting>
          </para>
      <para><emphasis>emdebian-tools</emphasis> also supports defaults that can be set via
          debconf with overrides for individual users:
<programlisting>
$ sudo dpkg-reconfigure emdebian-tools
</programlisting>
          or user-specific:
<programlisting>
$ cp /etc/emsource.conf ~/.dpkg-cross/emsource
$ editor ~/.dpkg-cross/emsource
</programlisting>
          </para>
      <note>
        <title>dpkg-cross older than 1.33</title>
        <para>dpkg-cross v1.32 and earlier contained some syntax errors relating
            to unitialised values in <filename>Debian::DpkgCross</filename>. If
            <emphasis>emdebian-tools</emphasis> 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
            <emphasis>emdebian-tools</emphasis>.
            </para>
      </note>
    </refsect2>
    <refsect2 id="components">
      <title>COMPONENTS</title>
      <para><command>emsetup</command> - Checks your system for cross-build
          support and determines some defaults for other emdebian-tools scripts.
          <emphasis role="bold">Run this first</emphasis>, using the
          simulate option to see what changes may be needed.</para>
      <para><command>emchain</command> - 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 <emphasis>unsupported</emphasis> by
          <command>emchain</command>; packages built using toolchains based on old
          versions of gcc should <emphasis>not</emphasis> be uploaded to the Emdebian
          target repository.
          </para>
      <para><command>emsource</command> - wrapper for
          <emphasis>apt-get source</emphasis> 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. <command>emsource</command>
          checks for an existing emdebianised source tree and runs
          <command>em_make</command> where appropriate. <command>emsource</command> is
          an optional component of <emphasis>emdebian-tools</emphasis>. If the package does not need to have patches in Emdebian SVN, <command>apt-get</command> <option>source</option> or <command>dget</command> <option>-x</option> can be used instead. (Remember to run <command>em_make</command> on the new Debian source if you do not use <command>emsource</command>.)
          </para>
      <para><command>em_make</command> - similar to dh_make for Debian,
      <command>em_make</command> 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. <filename>debian/rules</filename> is
      a special case as it has to be patched prior to running any other
      <filename>dpkg-*</filename> commands or executing <filename>debian/rules</filename>
      itself. <command>em_make</command> prepares suitable patches that are maintained
      and updated by <command>emdebuild</command>.
      </para>
      <note id="emlocaleremoval">
        <title>emlocale has been replaced</title>
        <para><command>emlocale</command> has been replaced by <command>em_installtdeb</command>
        which operates without <filename>$pkg-locale-$lang</filename> files and
        <filename>emdebian-$pkg-locale</filename> patch files and <emphasis>without
        changes to <filename>debian/control</filename></emphasis>. <command>em_installtdeb</command>
        runs at the end of the build (acting as a second build if the first completes
        successfully) and the results of the <command>em_installtdeb</command> run are checked
        with the same <command>emdebuild</command> build checks as before. This provides a second
        <filename>.changes</filename> file, a second <filename>.dsc</filename> file and a stripped
        down <filename>.tdeb.tar.gz</filename> tarball containing (hopefully) enough files for
        translators to prepare independent <emphasis>tdeb</emphasis> uploads. Emdebian has support
        for the necessary <emphasis>locale</emphasis> repository and the <emphasis>tdeb</emphasis>
        <filename>.changes</filename> file must <emphasis role="bold">NOT</emphasis> be uploaded
        to the normal Emdebian target repository, neither should <emphasis>tdeb</emphasis> files
        be uploaded to Debian at this time. See <command>em_installtdeb</command> (1).
        </para>
      </note>
      <para><command>emdebuild</command> - a wrapper script for
          <command>dpkg-buildpackage</command> using <option>-a</option> to specify the
          target architecture and <option> -uc -us -rfakeroot -D</option> as well as using
          the <emphasis>nodocs nochecks noudeb</emphasis> DEB_BUILD_OPTIONS. If this
          is the first release of an emdebian version of the package,
          <option>-sa</option> 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.
          </para>
    </refsect2>
  </refsect1>
  <refsect1>
    <title>FILES</title>
    <para><emphasis>emdebian-tools</emphasis> manages two configuration files:
    </para>
    <orderedlist>
      <listitem>
        <para><filename>/etc/emsource.conf</filename> : 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
    <command>apt-get</command> (true) or <command>aptitude</command> (false).
    </para>
        <note>
          <title>Local settings</title>
          <para>Values from <filename>emsource.conf</filename> can also be set
          locally on a per-user basis by copying <filename>/etc/emsource.conf</filename>
          to <filename>~/.dpkg-cross/emsource</filename> and editing the values.
          These settings will override any values in <filename>/etc/emsource.conf</filename>
          and will not be modified by <emphasis>emdebian-tools</emphasis>.
      </para>
        </note>
      </listitem>
      <listitem>
        <para>Installation changes</para>
        <blockquote>
          <para><filename>/etc/apt/sources.list.d/emdebian.sources.list</filename> :
    Provides the apt source for the Emdebian toolchain repository so that your
    cross-building toolchains can be installed and updated automatically.
    </para>
          <para><emphasis>emdebian-tools</emphasis> 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 <filename>/etc/apt/sources.list</filename> does not contain a
    primary Debian mirror, this file will include the default primary mirror
    for emdebian-tools: <filename>ftp.uk.debian.org</filename>. If you prefer to use
    a closer or faster primary mirror, please refer to the Debian Mirror List
    <ulink href="http://www.debian.org/mirror/list">http://www.debian.org/mirror/list</ulink>
    and add your preferred primary mirror to <filename>/etc/apt/sources.list</filename>,
    run 'apt-get update', then use 'dpkg-reconfigure emdebian-tools' to update
    <filename>/etc/apt/sources.list.d/emdebian.sources.list</filename>. At
    least one primary mirror, as defined on the DML page,
    <emphasis role="bold">must</emphasis> be available to use emdebian-tools.
    </para>
          <para>It is not possible to set repositories on a per-user basis.
    </para>
        </blockquote>
      </listitem>
    </orderedlist>
    <para><emphasis>emdebian-tools</emphasis> uses the specified Emdebian working directory
      for <command>emsource</command>, <command>empdebuild</command> and
      <command>emsandbox</command>. chroot and rootfs tarballs are created in $WORK and the
      value of $WORK itself is set in <filename>/etc/emsource.conf</filename> using debconf.
      If $WORK represents your Emdebian working directory, <emphasis>emdebian-tools</emphasis>
      uses this subdirectory hierarchy:
      </para>
    <itemizedlist>
      <listitem>
        <para>$WORK/machine/
            </para>
        <blockquote>
          <para>Contains machine specific configuration data used by <command>emsandbox</command>
          and <command>emsource</command>.
              </para>
        </blockquote>
        <itemizedlist>
          <listitem>
            <para>$WORK/machine/$MACHINE</para>
            <blockquote>
              <para>One directory for each type of machine. $MACHINE represents the machine name.
                  </para>
            </blockquote>
            <itemizedlist>
              <listitem>
                <para>$WORK/machine/$MACHINE/$VARIANT</para>
                <blockquote>
                  <para>One directory for each variant of each type of machine. Variant is the variant
                      name. If none is specified, <filename>$WORK/machine/$MACHINE/default</filename>
                      is used.
                      </para>
                </blockquote>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>$WORK/pbuilder/</para>
        <blockquote>
          <para>Top level directory for <command>empdebuild</command>.
          </para>
        </blockquote>
        <itemizedlist>
          <listitem>
            <para>aptcache</para>
            <blockquote>
              <para>Cached packages for cross-building emdebianised packages in a build chroot.
                Note that this directory will contain packages from your host architecture
                <emphasis>and</emphasis> packages for your target architecture(s) that were needed
                as cross dependencies for other builds and downloaded by <command>apt-cross</command>.
                </para>
            </blockquote>
          </listitem>
          <listitem>
            <para>result</para>
            <blockquote>
              <para>
                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).
                </para>
            </blockquote>
          </listitem>
          <listitem>
            <para>build</para>
            <blockquote>
              <para>Should be empty. <command>empdebuild</command> unpacks the cross-building
                chroot into this directory, using the process ID of <command>empdebuild</command>
                as the name of a new subdirectory. Any subdirectories left in <filename>build/</filename>
                can be deleted once the build completes successfully.
                </para>
            </blockquote>
          </listitem>
        </itemizedlist>
      </listitem>
      <listitem>
        <para>trunk</para>
        <blockquote>
          <para>The top level of the <command>emsource</command> 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.
          </para>
          <para>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
          <command>emsource</command> knows which hierarchy is your $WORK, even if you
          forget.
          </para>
        </blockquote>
      </listitem>
    </itemizedlist>
    <para><command>apt-cross</command> also creates apt cache data used by emdebian-tools
        and this is typically stored in <filename>~/.apt-cross/</filename>.
        </para>
  </refsect1>
  <refsect1>
    <title>COLOUR</title>
    <para><filename>emdebian-tools</filename> support colourised output to supporting
  terminals using Text::ANSIColor. This can be disabled by setting the environment
  variable <option>ANSI_COLORS_DISABLED</option>. 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 <filename>emdebian-tools</filename> 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.
  </para>
  </refsect1>
  <refsect1>
    <title>Author</title>
    <para>The <emphasis>emdebian-tools</emphasis> scripts were written
      by Neil Williams <email>codehelp@debian.org</email>.
    </para>
    <para>This manual page was written by Neil Williams
      <email>codehelp@debian.org</email>
    </para>
  </refsect1>
  <refsect1 id="overviewseealso">
    <title>SEE ALSO</title>
    <para><command>apt-cross</command> (1), <command>dpkg-cross</command> (1),
        <command>em_make</command> (1), <command>em_installtdeb</command> (1),
        <command>emchain</command> (1), <command>emsource</command> (1),
        <command>emdebuild</command> (1), <command>emsetup</command> (1),
        <command>emsandbox</command> (1).
        </para>
    <para>WWW versions of these manpages:
    <ulink url="http://linux.codehelp.co.uk/emdebian/man/">
    http://linux.codehelp.co.uk/emdebian/man/</ulink>
    </para>
  </refsect1>
</refentry>