emchain [[-l] | [--log]] [[-a] | [--arch] ARCH] [[-w] | [--workdir] DIR] [[-v] | [--verbose]] [[-q] | [--quiet]]
emchain [[-l] | [--log]] [[-a] | [--arch] ARCH] [[-w] | [--workdir] DIR] [[-v] | [--verbose]] [[-q] | [--quiet]] [[-f] | [--force]]
emchain [[-l] | [--log]] [[-a] | [--arch] ARCH] [[-w] | [--workdir] DIR] [[-v] | [--verbose]] [[-q] | [--quiet]] [[-i] | [--ignore]]
emchain [[-l] | [--log]] [[-a] | [--arch] ARCH] [[-w] | [--workdir] DIR] [[-v] | [--verbose]] [[-q] | [--quiet]] [[-u] | [--uclibc]]
emchain [[-h] | [--help]] [[--version]]
emchain 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: http://www.emdebian.org/.
emchain uses dpkg-cross and
apt-cross 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.
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 emchain and allow plenty of
time to build your toolchain. emchain is designed to
run unattended and supports a --log so that you won't miss
any errors or messages. If the build fails, emchain can
be restarted without duplicating previous work.
uClibc support is experimental (and incomplete) and depends on an existing toolchain for gcc and glibc being already installed.
-l|--logCreate a build log in the working directory. If -v is
used, the log will also contain content from apt-cross and dpkg-cross calls
made by emchain.
-a|--arch ARCHSpecify the target architecture.
Default is set by dpkg-cross using debconf.
-w|--workdir DIROverride the user specified working directory in
~/.dpkg-cross/emsource. Intended to support users who
usually build one particular emchain but later need to build an alternative
chain whilst retaining the default chain.
-f|--forceemchain 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 emchain to attempt to continue the build.
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 force should NOT be
installed and emchain disables automatic installation of forced packages
for this reason.
-u|--uclibcuClibc support is experimental!
A standard glibc toolchain must be installed before the package built using this option can be used.
-v|--verbosebe verbose. -v can be repeated to increase verbosity,
up to a maximum of three times. When running emchain directly,
it is recommended to use at least one -v option.
-q|--quietbe quiet (default) - can also be used to reduce verbosity set
using -v.
emchain needs to be run in a consistent working directory
so that emchain, apt-cross and
apt-get source can check if work has already been done. If a
working directory has not been specified for emdebian-tools
using debconf, or if the specified working directory does not exist,
the current directory will be used.
When temporarily overriding the previous working directory, it is worth
copying all *.orig.tar.gz, *.dsc and
*.diff.gz files from another build to save download time, then
use dpkg-source to unpack each source.
emchain uses the current default architecture setting
of dpkg-cross - managed by debconf
in dpkg-cross (>= 1.33). Prior to version 1.33,
dpkg-cross used ~/.dpkg-cross/cross-compile,
copied from /etc/dpkg-cross/cross-compile and
manually edited to update the default_arch:
# default architecture for dpkg-cross (to avoid always typing the -a option # if you do cross installations only for one architecture) # default_arch =
emchain checks your apt-cache 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. emchain will
build and install the new toolchain packages as soon as the upstream Debian
buildd machine has completed the process.
If the upstream buildd for the specified architecture fails to build the current version of one of the toolchain packages, emchain will abort with a "Mismatch in source version" error. It is unlikely that emchain will be able to build a usable 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 emchain 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 http://www.emdebian.org/ 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 Debian BTS.
Other failures can be due to missing build dependencies for some of the toolchain
packages. To keep the dependencies of emdebian-tools manageable for
users who do not use emchain, these build dependencies will need to
be installed separately. The dpkg output at the point at which
emchain failed will indicate which packages need to be installed.
Once such dependencies are installed, simply restart emchain to
pick up where you left off. Some dependencies may differ between target architectures so
that emchain may fail for one architecture when another architecture
would succeed on the same system.
It can be difficult to build toolchains for new architectures -
emchain will try to help you but when a native
gcc 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
dpkg-cross, patch the gcc build scripts or run customised
dpkg-buildpackage environments to ensure the correct
build environment and dependencies are available. Consider using the
--log option of emchain with a 'known' build
and comparing with the log from the new architecture. emchain
does require that the new architecture is at least supported by
dpkg-cross before beginning to build a toolchain.
If the upstream sources need to be patched or if you need to use source packages from outside Debian, note that emchain 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, emchain 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.
To be able to install the cross-built packages,
emchain needs a usable sudo
implementation. Ensure sudo is available to the user
running emchain.
emchain was written
by Neil Williams <codehelp@debian.org>.
This manual page was written by Neil Williams
<codehelp@debian.org>