--- name: "emchain" section: "1" platform: "linux" package: "emdebian-tools" version: "1.4.3" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/emchain" --- # emchain(1) keeping cross-built toolchains in step with Debian. ## 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 \. This manual page was written by Neil Williams \ ## SEE ALSO See also *apt-cross* (1), *dpkg-cross* (1), *em\_make* (1), *emdebuild* (1), *emdebian-tools* (1). ## AUTHOR **Emdebian** **Neil Williams** - Author. ## COPYRIGHT