Toolchain is a collection of tools used to develop software for a certain hardware target. Toolchains are based on
particular versions of compiler, libraries, special headers and other tools. A cross-toolchain is a toolchain for
compiling binaries for different CPU architecture than the host CPU.
Scratchbox is a cross-compilation toolkit for embedded Linux application development. It is designed for compiling
software for different target CPU architectures. Scratchbox allows creating several target environments. Each target is
a separate environment that has a selected toolchain, target CPU and an own file system.
Building toolchains is not always trivial. Scratchbox uses scripts for building predefined toolchains. After
building a toolchain it should be tested to know that it works properly. Testing toolchains is harder than building
Scratchbox toolchains provide the cross compilation tools for compiling binaries for the target environment. Each
toolchain is built for a certain CPU target and they are based on certain gcc and C-library sources.
Scratchbox toolchains can be used both inside and outside Scratchbox. In Scratchbox each target uses a certain
toolchain with a specific target CPU. Scratchbox uses wrappers to make the toolchains appear as if they were native
toolchains. Outside Scratchbox the toolchains are used as any normal cross compilation toolchains.
All the installed toolchains can be found in the /scratchbox/compilers directory.
The toolchains use either glibc or uClibc C-libraries. The glibc toolchain is based on the Debian patched
glibc-2.3.2. Other packages used for building the toolchains are binutils, gcc and linux kernel headers. Several
patches are used when building the toolchains. The patching depends of the used toolchains configurations and used
packages. eg. when using uClibc then binutils and gcc are patched with uClibc patches.
Scratchbox.org  offers prebuilt toolchains for x86 and ARM targets. Only these targets are
currently supported because too much work to support all different configurations. With the Scratchbox toolchain
sources you can build your own custom toolchains.
Scratchbox toolchain building scripts allow you to build easily predefined toolchains and give the possibility to
build custom toolchains for different targets. Changing the toolchain binutils, compiler or C-library packages can be a
more demanding task.
Scratchbox uses a gcc wrapper for wrapping most of the
toolchain command binaries. In the /scratchbox/compilers/bin/ directory you can see the
linked binaries. The wrapper knows how to handle each command and depending on the command it might change some of the
command parameters. Then it runs the actual command from the correct path that depends from the selected target. The
gcc wrapper reads all the target specific information from the target configuration files that can be found in the /scratchbox/users/username/targets/ directory.
Scratchbox has also an ld wrapper for linking the binaries
properly. When compiling inside Scratchbox a fake-native ld is
used. Outside Scratchbox a normally behaving ld is used. For example inside Scratchbox the dynamically linked binaries
are linked against the libraries that are in standard library paths, not in the toolchain's library path.
The gcc wrapper uses ccache by default. The default cache directory is /scratchbox/ccache/. Ccache can be disabled by setting the environment variable SBOX_USE_CCACHE to
"no". The cache directory can be changed with the CCACHE_DIR environment variable.
Scratchbox toolchain build scripts are available in the sb-toolchains source package that is available at the Scratchbox download page  for each Scratchbox version.
Scratchbox toolchains are built with the GAR system . It is a mechanism for automating the
compilation and installation of third-party source code. It appears in the form of a tree of directories containing
Makefiles and other ancillary bookkeeping files (such as installation manifests and checksum lists).
The toolchains can currently be built with two different systems. The old one uses the sb-toolchains/meta/target-kit directory. When the new system uses the sb-toolchains/meta/gcc-glibc directory.
The old system allows only selecting the target architecture, compiler name and the build directory. It doesn't
select the used source packages or patched that are applied. The new toolchain build system is far more flexible. It
uses configuration files for building toolchains. The configuration file is passed to the meta makefile as a
The new build system uses separate build directories for separate toolchain build phases. This makes it's more
flexible to change build components in the toolchain build. eg. changing gcc's configuration arguments without breaking
the the build system for other toolchains. This would be done by creating a new build directory under the sb-toolchains/cc directory and changing the CC_DIR variable in the config file.
The sb-toolchains source package is used also to build arch
tools and device tools which are target dependent. The
build instructions in this document automatically build all of them; there is currently no documented way to disable
Toolchains have to be built with an already existing compiler. Scratchbox has the HOST target for this. HOST's
host-gcc toolchain is for compiling binaries for the host. It's configured to make the compiled binaries use the
Scratchbox's host libraries.
When building toolchains you need write privileges to the /scratchbox/compilers and /scratchbox/device_tools directories. The scratchbox source package contains the scripts/permhack script for
changing the privileges, but you can also do it like this:
The following will explain toolchain building with the new system.
The toolchain configuration file includes information like compiler name, target architechture, softfloat support
and all source package and patch information. For example see the existing configuration files in the sb-toolchains/meta/gcc-glibc directory.
For each toolchain component there are the several variables. eg. for the C-library:
version number of the C-library
the build directory of the C-library headers
the build directory of the C-library
the C-library source tar
the patches that are applied to the source tar
a special script that can be used to apply complex patches
The sb-toolchains/packaging/create_packages script generates deb and rpm packages from the compiled toolchains. If
you have made changes to the packages then fix the version numbers in the sb-toolchains/packaging/common.var file. At
the moment the script supports only creating arm, ppc and x86 toolchain packages.
For packaging one toolchain use the ./build_one_toolchain script. Run it outside Scratchbox so it can also create
All created compilers should be at least tested to compile, link and run a simple test program. The test program
should be tested to link both statically and dynamically. These tests should be done with both a C and a C++
The sb-toolchains/test_tools/test_scripts/reg_tests.sh script can be used for these
These tests are a collection of test for the C and C++ frontends of gcc. The tests can be found in gcc's directory
The result of running the testsuite are various *.sum and *.log files in the testsuite subdirectories. The *.log
files contain a detailed log of the compiler invocations and the corresponding results, the *.sum files summarise the
results. These summaries contain status codes for all tests:
PASS: the test passed as expected
XPASS: the test unexpectedly passed
FAIL: the test unexpectedly failed
XFAIL: the test failed as expected
UNSUPPORTED: the test is not supported on this platform
ERROR: the testsuite detected an error
WARNING: the testsuite detected a possible problem
The Scratchbox toolchains should be tested with these tests. These tests can be run with reg_tests.sh (see Section 4.1) or manually as described in GCC Testing .