emchain(1)
NAME
emchain - keeping cross-built toolchains in step with Debian.
SYNOPSIS
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]]
DESCRIPTION
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.
OPTIONS
- -l|--log
- Create 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 ARCH
- Specify the target architecture. Default is set by dpkg-cross using debconf.
- -w|--workdir DIR
- Override 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|--force
- emchain 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. - Only use force if you know what you are doing
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|--uclibc
uClibc support is experimental!- A standard glibc toolchain must be installed before the package
built using this option can be used. - -v|--verbose
- be 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|--quiet
- be quiet (default) - can also be used to reduce verbosity set using -v.
WORKING DIRECTORY
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.
FAILURES
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.
TOOLCHAINS FOR UNSUPPORTED OR NEW ARCHITECTURES.
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.
DEPENDENCIES
To be able to install the cross-built packages, emchain needs a usable
sudo implementation. Ensure sudo is available to the user running
emchain.
AUTHOR
emchain was written by Neil Williams <codehelp@debian.org>.
This manual page was written by Neil Williams <codehelp@debian.org>
SEE ALSO
See also apt-cross (1), dpkg-cross (1), em_make (1), emdebuild (1),
emdebian-tools (1).
AUTHOR
Emdebian
- Neil Williams
- Author.