emchain

Langue: en

Version: Sun 11 Jan 2009 19:55:45 GMT (debian - 07/07/09)

Section: 1 (Commandes utilisateur)

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, according to the targetsuite value set in debconf. To build toolchains for other suites, either use dpkg-reconfigure libemdebian-tools-perl or override the system default targetsuite by copying /etc/emsource.conf to ~/.apt-cross/emsource and set the override there. To build toolchains for older compilers, see the Emdebian website: http://www.emdebian.org/.

Emdebian already provides pre-built toolchains for most situations, ensure you check m[blue]the Emdebian websitem[][1] before spending time on emchain.

emchain uses dpkg-cross and apt-cross to determine the latest versions of toolchain packages available in the selected targetsuite, 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

Debian and Emdebian developer.

NOTES

1.
the Emdebian website
http://www.emdebian.org/tools/crosstools.html