<?xml version="1.0" encoding="UTF-8"?>
<refentry id="emchain1">
  <refentryinfo>
    <productname>emchain</productname>
    <productnumber>1</productnumber>
  </refentryinfo>
  <refmeta>
    <refentrytitle>emchain</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">EMDEBIAN-TOOLS</refmiscinfo>
    <refmiscinfo class="manual">EMDEBIAN-TOOLS</refmiscinfo>
  </refmeta>
  <refnamediv id="name">
    <refname>emchain</refname>
    <refpurpose>keeping cross-built toolchains in step with Debian.</refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>emchain</command>
      <group>
        <arg>-l</arg>
        <arg>--log</arg>
      </group>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-w</arg>
        <arg>--workdir</arg>
        <replaceable> DIR</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emchain</command>
      <group>
        <arg>-l</arg>
        <arg>--log</arg>
      </group>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-w</arg>
        <arg>--workdir</arg>
        <replaceable> DIR</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <group>
        <arg>-f</arg>
        <arg>--force</arg>
      </group>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emchain</command>
      <group>
        <arg>-l</arg>
        <arg>--log</arg>
      </group>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-w</arg>
        <arg>--workdir</arg>
        <replaceable> DIR</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <group>
        <arg>-i</arg>
        <arg>--ignore</arg>
      </group>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emchain</command>
      <group>
        <arg>-l</arg>
        <arg>--log</arg>
      </group>
      <group>
        <arg>-a</arg>
        <arg>--arch</arg>
        <replaceable> ARCH</replaceable>
      </group>
      <group>
        <arg>-w</arg>
        <arg>--workdir</arg>
        <replaceable> DIR</replaceable>
      </group>
      <group>
        <arg>-v</arg>
        <arg>--verbose</arg>
      </group>
      <group>
        <arg>-q</arg>
        <arg>--quiet</arg>
      </group>
      <group>
        <arg>-u</arg>
        <arg>--uclibc</arg>
      </group>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>emchain</command>
      <group>
        <arg>-h</arg>
        <arg>--help</arg>
      </group>
      <group>
        <arg>--version</arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1 id="description">
    <title>DESCRIPTION</title>
    <para><command>emchain</command> implements the EmdebianSlind toolchain
        build process for the latest versions of gcc, binutils and libc. To build
        toolchains for older compilers, see the Emdebian website:
    <link url="http://www.emdebian.org/">http://www.emdebian.org/</link>.
    </para>
    <para><command>emchain</command> uses <filename>dpkg-cross</filename> and
    <filename>apt-cross</filename> to determine the latest
    versions of toolchain packages, downloads the source for each missing
    package, builds the package using EmdebianSlind options and commands and
    installs the cross-built packages and toolchain packages.</para>
    <para>Building a cross-building toolchain requires a sizeable download of source
    code and a lot of compilation. A toolchain download can typically involve
    a 75Mb download. Compiling the code can result in almost a gigabyte of
    data in the working directory. Completed toolchain package files can require
    over 16Mb and an installed size of 20Mb or more. Ensure sufficient space is
    available before starting <command>emchain</command> and allow plenty of
    time to build your toolchain. <command>emchain</command> is designed to
    run unattended and supports a <option>--log</option> so that you won't miss
    any errors or messages. If the build fails, <command>emchain</command> can
    be restarted without duplicating previous work.
    </para>
    <para><emphasis>uClibc support is experimental</emphasis> (and incomplete)
    and depends on an existing toolchain for gcc and glibc being already installed.
    </para>
  </refsect1>
  <refsect1 id="options">
    <title>OPTIONS</title>
    <variablelist remap="TP">
      <varlistentry>
        <term><option>-l</option>|<option>--log</option></term>
        <listitem>
          <para>Create a build log in the working directory. If <option>-v</option> is
        used, the log will also contain content from apt-cross and dpkg-cross calls
        made by emchain.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-a</option>|<option>--arch</option><replaceable> ARCH</replaceable></term>
        <listitem>
          <para>Specify the target architecture.
          Default is set by <filename>dpkg-cross</filename> using debconf.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-w</option>|<option>--workdir</option><replaceable> DIR</replaceable></term>
        <listitem>
          <para>Override the user specified working directory in
      <filename>~/.dpkg-cross/emsource</filename>. Intended to support users who
      usually build one particular emchain but later need to build an alternative
      chain whilst retaining the default chain.
      </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-f</option>|<option>--force</option></term>
        <listitem>
          <para><command>emchain</command> checks the current apt-cache to see if the Debian buildd
          system has successfully completed on the requested architecture and complains of a mismatch
          in source versions if it appears that the version available for the requested cross-architecture
          is not the same as the version available for the build architecture. It is unlikely that emchain
          will be able to build a usable cross-compiler when the native build has already failed. Normally,
          you should run emchain again when the buildd has completed successfully. However, if you have checked
          the Debian build logs and you know what you are doing, you can request <command>emchain</command>
          to attempt to continue the build.
          </para>
          <note>
            <title>Only use force if you know what you are doing</title>
            <para>It would be trivially easy to build a useless toolchain using this option. The intention
            is to support test builds, for internal Emdebian testing and to debug the build process itself.
            Packages built using <option>force</option> should <emphasis role="bold">NOT</emphasis> be
            installed and <command>emchain</command> disables automatic installation of forced packages
            for this reason.
            </para>
          </note>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-u</option>|<option>--uclibc</option></term>
        <listitem>
          <para>
            <emphasis>uClibc support is experimental!</emphasis>
          </para>
          <para>A standard glibc toolchain must be installed before the package
          built using this option can be used.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-v</option>|<option>--verbose</option></term>
        <listitem>
          <para>be verbose. <option>-v</option> can be repeated to increase verbosity,
      up to a maximum of three times. When running <command>emchain</command> directly,
      it is recommended to use at least one <option>-v</option> option.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>-q</option>|<option>--quiet</option></term>
        <listitem>
          <para>be quiet (default) - can also be used to reduce verbosity set
        using <option>-v</option>.
        </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1 id="location">
    <title>WORKING DIRECTORY</title>
    <para><command>emchain</command> needs to be run in a consistent working directory
    so that <filename>emchain</filename>, <filename>apt-cross</filename> and
    <filename>apt-get source</filename> can check if work has already been done. If a
    working directory has not been specified for <filename>emdebian-tools</filename>
    using debconf, or if the specified working directory does not exist,
    the current directory will be used.
    </para>
    <para>When temporarily overriding the previous working directory, it is worth
       copying all <filename>*.orig.tar.gz</filename>, <filename>*.dsc</filename> and
       <filename>*.diff.gz</filename> files from another build to save download time, then
       use <filename>dpkg-source</filename> to unpack each source.
    </para>
    <para><command>emchain</command> uses the current default architecture setting
    of <command>dpkg-cross</command> - managed by <command>debconf</command>
    in <command>dpkg-cross</command> (&gt;= 1.33). Prior to version 1.33,
    <filename>dpkg-cross</filename> used <filename>~/.dpkg-cross/cross-compile</filename>,
    copied from <filename>/etc/dpkg-cross/cross-compile</filename> and
    manually edited to update the default_arch:
<programlisting>
# default architecture for dpkg-cross (to avoid always typing the -a option
# if you do cross installations only for one architecture)
# default_arch =
</programlisting>
    </para>
    <para><command>emchain</command> checks your <filename>apt-cache</filename> for
    updated toolchain packages available in the target architecture. Note that there
    may be a delay between new toolchain packages being available for your host
    architecture and your target architecture. <command>emchain</command> will
    build and install the new toolchain packages as soon as the upstream Debian
    buildd machine has completed the process.
    </para>
  </refsect1>
  <refsect1 id="failures">
    <title>FAILURES</title>
    <para>If the upstream buildd for the specified architecture fails to build the current
    version of one of the toolchain packages, <command>emchain</command> will abort with
    a "Mismatch in source version" error. It is unlikely that <command>emchain</command> will
    be able to build a <emphasis role="bold">usable</emphasis> toolchain using the new upstream
    version - even if the cross-build may otherwise appear to succeed. An existing toolchain
    (typically the previous version) will be unaffected - this failure only affects the
    creation of new toolchains. Unfortunately, there is little that
    <command>emchain</command> can do other than highlight the failure to build from source
    (FTBFS) on the requested architecture. To build a new toolchain manually, you will need
    to obtain the previous version of the source and follow the build instructions
    on <link url="http://www.emdebian.org/">http://www.emdebian.org/</link>
    or wait until the problem has been fixed upstream. You may wish to check for an existing
    FTBFS bug report against the affected package in the
    <link url="http://www.uk.debian.org/Bugs/">Debian BTS</link>.
    </para>
    <para>Other failures can be due to missing build dependencies for some of the toolchain
    packages. To keep the dependencies of <emphasis>emdebian-tools</emphasis> manageable for
    users who do not use <command>emchain</command>, these build dependencies will need to
    be installed separately. The <filename>dpkg</filename> output at the point at which
    <command>emchain</command> failed will indicate which packages need to be installed.
    Once such dependencies are installed, simply restart <command>emchain</command> to
    pick up where you left off. Some dependencies may differ between target architectures so
    that <command>emchain</command> may fail for one architecture when another architecture
    would succeed on the same system.
    </para>
  </refsect1>
  <refsect1>
    <title>Toolchains for unsupported or new architectures.</title>
    <para>It can be difficult to build toolchains for new architectures -
    <command>emchain</command> will try to help you but when a native
    <filename>gcc</filename> build is not available for any version on the requested
    architecture, cross building a toolchain may fail. In particular, you
    may have to build packages that would otherwise be available via
    <filename>dpkg-cross</filename>, patch the gcc build scripts or run customised
    <filename>dpkg-buildpackage</filename> environments to ensure the correct
    build environment and dependencies are available. Consider using the
    <option>--log</option> option of <filename>emchain</filename> with a 'known' build
    and comparing with the log from the new architecture. <command>emchain</command>
    does require that the new architecture is at least supported by
    <filename>dpkg-cross</filename> before beginning to build a toolchain.
    </para>
    <para>If the upstream sources need to be patched or if you need to use
    source packages from outside Debian, note that <command>emchain</command>
    will skip downloading new sources if files with a matching filename exist
    in the chosen working directory. Provided that your modified sources retain
    the same filenames as the current upstream Debian sources, <command>emchain</command>
    will use those sources. This is useful when testing patches or build changes but
    toolchains built in this way should not be uploaded to Emdebian repositories -
    post the patches to the upstream Debian package and rebuild an 'official' toolchain
    once the Debian package is updated.
    </para>
  </refsect1>
  <refsect1>
    <title>DEPENDENCIES</title>
    <para>To be able to install the cross-built packages,
    <command>emchain</command> needs a usable <filename>sudo</filename>
    implementation. Ensure <filename>sudo</filename> is available to the user
    running <command>emchain</command>.
    </para>
  </refsect1>
  <refsect1>
    <title>Author</title>
    <para><command>emchain</command> was 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="emchainseealso">
    <title>SEE ALSO</title>
    <para>See also <filename>apt-cross</filename> (1), <filename>dpkg-cross</filename> (1),
        <filename>em_make</filename> (1),
        <filename>emdebuild</filename> (1), <filename>emdebian-tools</filename> (1).
        </para>
  </refsect1>
</refentry>