Firmware Linux (FWL) is an embedded Linux build system designed to eliminate the need for cross compiling, replacing it with native compiling under emulation instead.
FWL consists of a series of shell scripts which create a complete bootable linux system for a given target hardware platform. This provides a minimal native Linux build environment for the target, loosely based on Linux From Scratch (stripped down to an embedded variant built from busybox, uClibc, gcc, binutils, make, bash, and the Linux kernel). Running this native build environment under an emulator such as QEMU (or on real target hardware if applicable) allows fully native builds for arbitrary target platforms to be performed on cheap and powerful commodity PC hardware.
The currently supported target hardware platforms include arm, mips, powerpc, x86, and x86-64, with partial support for sh4, mips, and sparc.
Firmware Linux is loosely based on Linux From Scratch, stripped down and rebased on busybox and uClibc.
Intermediate stages of the build (such as the cross compiler and the unpackaged root filesystem directory) may also be useful to Linux developers, and are also packaged up in the build subdirectory.
The default build provides a native development environment for each target platform, eliminating the need for cross compiling in favor of native compiling under emulation.
Each system-image tarball contains an ext2 root filesystem image, a kernel configured to run under qemu, and shell scripts to run the system (in various modes) under the emulator qemu.
To test boot an FWL target system under qemu 0.9.1, download the appropriate prebuilt binary tarball for the target you're interested in, extract it, cd into it, and execute one of the following shell scripts:
./run-emulator.sh - This boots the target Linux system under the appropriate emulator, with /dev/console hooked to the emulator's stdin and stdout. (I.E. the shell prompt the script gives you after the boot messages is running in the emulator.) Type "cat /proc/cpuinfo" to confirm you're running in the emulator, then play around and have fun.
./run-with-home.sh - Wrapper for run-emulator.sh which adds a second virtual hard drive mounted on /home. (If the file "hdb.img" doesn't exist on the host, this script automatically creates a 2 gigabyte sparse file and formats it ext3.)
./run-with-distcc.sh - Wrapper for run-with-home.sh which sets up the appropriate magic so the emulator will automatically call out to the cross compiler on the host system via distcc. This can significantly speed up build times under the emulator, while still avoiding most of the complexity of cross compiling. (More info)
The FWL boot script for qemu (/tools/bin/qemu-setup.sh) populates /dev from sysfs, sets up an emulated (masquerading) network (so you can wget source packages or talk to distcc), and creates a few symlinks needed to test build normal software packages (such as making /lib point to /tools/lib). It also mounts /dev/hdb (or /dev/sdb) on /home if a second emulated drive is present.
For most platforms, exiting the command shell will exit the emulator. (Some, such as powerpc, don't support this yet. For those you have to kill qemu from another window, or exit the xterm. I'm working on it.)
To use this emulated system as a native build environment, see native compiling.
The cross compiler created during the FWL build is a relocatable C compiler for the target platform. To use it on its own, download the appropraite cross compiler tarball for the host you're running on and the target you'd like to compile for. Extract the compiler tarball and add the cross-compiler-$TARGET/bin directory to your $PATH, then use $TARGET-gcc as your cross compiler and "$TARGET-" as your CROSS prefix for packages with cross compiling support.
For example, if you download cross-compiler-armv4l and extract it into your home directory, set "PATH=~/cross-compiler-armv4l/bin:$PATH", use armv4l-gcc to build code, and use "CROSS=armv4l-" to set your cross compiler prefix.
Note that this cross compiler does not support C++. If you need C++ support, use the native compiling environment.
If you want to run this system on real hardware, you'll generally have to tweak and repackage the root filesystem. To make this easier, tarballs of each target's prebuilt root filesystem are available.
This root filesystem is a minimal native build environment for the target platform. This means it contains a compiler and associated build tools capable of building a complete new Linux system under itself, although you may have to bootstrap your way up (I.E. building things like zlib or perl before building momre complicated packages).
The vast majority of the space taken up by this filesystem is the development toolchain and associated support files (mostly header files and libraries).
If you're doing anything fancy, you'll probably want to rebuild it from source.
To build FWL, download the most recent source tarball, extract it, cd into it, and run "./build.sh". This script takes one argument, which is the target to build for. Run it with no arguments to see available targets. The resulting files are created in the "build" directory, including all the downloadable tarballs. (To perform a clean build, "rm -rf build" and re-run build.sh.)
By default, this Linux system is a minimal native build environment for the target platform. It contains a compiler and associated build tools capable of building a complete new Linux system under itself. This is is to support native compiling, which allows you to build a new (possibly smaller) root filesystem for your target.
If you don't want to bother with that, set the environment variable "BUILD_SHORT=1" before running the build to skip building the native toolchain. This results in a much, much smaller root filesystem, and also moves it up out of the /tools directory, but makes adding additional software to the resulting system much more difficult (as it must be done via cross compiling).
See native compiling under emulation and customizing mini-native for more information.
The build.sh script is a simple wrapper which calls the other scripts in sequence:
Another script, forkbomb.sh, performs a similar function but builds all supported targets at once.
include.sh - Common functions.
This script is not run directly, but is instead included from the other scripts to set up the build directory and provide common functions like "setupfor" and "cleanup". See anatomy of include.sh for details.
download.sh - Download source packages into sources/packages.
This script does not take any arguments, and writes its output into the sources/packages directory.
This script consists of a list of URLs and associated sha1sum values of all the source packages used by the build. It calls the "download" function out of include.sh to wget each package from its source location (or one of the mirrors listed in the download function) for which the specified sha1sum doesn't match. (If a package's sha1sum is set blank, any value is accepted and the package will only be downloaded if it doesn't exist.)
Re-running this script will re-validate each sha1sum, but won't download new packages as long as the sha1sums match. It automatically deletes any files from sources/packages which are no longer listed in the download script, such as old package versions.
host-tools.sh - Compile various packages to be used during the build, installing them into build/host.
This script does not take any arguments. In theory this is an optional step, and may be omitted. (In practice, package-mini-native.sh currently needs User Mode Linux and won't run without it. See the description of that script for details.)
The primary purpose of the host-tools.sh script is to isolate the build from dependencies on the host distribution. It does this by building host versions of the same command line utilities that will exist in the final mini-native development environment, and by creating symlinks to the host versions of the remaining tools (thus enumerating exactly which ones those are).
This allows build.sh set the $PATH to point only to the build/host directory, so no other tools from the host are used. (In reality, a few such as /bin/bash are referred to by absolute path, but it's not a big issue.) This helps to ensure that the resulting Linux system can rebuild itself under itself, because it already did.
A secondary purpose of host-tools.sh is to build packages (such as distcc and User Mode Linux) which may not be installed on the host system.
Note that this script no longer attempts to build qemu, due to the unreasonable requirement of installing gcc 3.x on the host. The FWL build scripts do not use qemu (except as an optional test at the end of cross-compiler.sh which is skipped if qemu is not available). You will need to install qemu (or find real hardware) to run the resulting images, but they should build just fine without it.
See anatomy of host-tools.sh for more information.
Currently, host-tools.sh builds toybox and busybox, and creates symlinks to the host's compiler toolchain (ar, as, nm, cc, gcc, make, ld), plus a few utilities that still need to be added to toybox (bzip2, find, install, od, sort, diff). Note that until that last category is eliminated, rebuilding the system under itself requires natively building and installing the bzip2, coreutils, and diffutils packages as a bootstrapping step.
cross-compiler.sh - Build a cross compiler (binutils, gcc, uClibc, linux kernel headers, and a wrapper script).
This script takes one argument: the architecture to build for.
Along the way, the build produces a relocatable cross compiler for the target hardware. Additional packages can be added to However, cross compiling additional packages is not recommended because the defaultroot filesystem of the bootable system contains development tools, and can act as a native build environment capable of compiling software on the target. (To overcome most of the speed penalty of emulation, use run-with-distcc.sh script.)
Thus the easy way to build software for a target is to compile To use FWL, download...
This bootable Linux system contains development tools, and can act as a minimal native build environment. If you run it under an emulator (or on real hardware) you can compile Along the way, the build produces a relocatable cross compiler for the target hardware, and also a native build environment capable of compiling software on the target.
The build system is a series of shell scripts which download, compile, install, and use the appropriate source packages to generate the output files. These shell scripts are designed to be easily read and modified.
The system built by these scripts consists of the following source packages:
Firmware Linux is licensed under GPL version 2. Its component packages are licensed under their respective licenses (mostly GPL and LGPL).
build.sh: Start here. This is the master script which runs all the other build stages. It takes one argument, the platform to build for. (Run it with no arguments to see a list of supported platforms.) The individual stage scripts can also be run individually, with the same argument as build.sh.
download.sh: This script checks the sources/packages directory for source tarballs, and downloads any that are missing or have invalid SHA1 checksums. It also deletes any old files in sources/packages not used by the current build version, and populates sources/build-links with version-independent symlinks for use by later build stages.
cross-compiler.sh: This script produces a cross compiler for the indicated target platform. The working copy is produced in the build directory, and a copy is saved as "cross-compiler-$ARCH.tar.bz2" for use outside the build system. This cross compiler is fully relocatable (using the wrapper script in sources/toys/gcc-uClibc.c), so and any normal user can extract it into their home directory, add cross-compiler-$ARCH/bin to their $PATH, and run $ARCH-gcc to create target binaries. It contains gcc, binutils, linux kernel headers, and the uClibc C library.
The cross compiler script also builds squashfs tools, a target platform emulator (QEMU), and uses the emulator to confirm that the cross compiler works. This script can take an optional first argument, --short, to skip those steps. This is useful if you want to build several cross compilers without multiple copies of QEMU. (The short build will also delete the build/cross-compiler-$ARCH directory after tarring it up, since the result isn't usable by later build stages.)
mini-native.sh: This script uses the cross compiler to create a minimal native build environment for the target platfrom. This native environment consists of just seven packages: busybox, uClibc, the linux kernel, gcc, binutils, make, and bash. This is a fully self-hosting development environment, capable of rebuilding itself from source code, organized as a Linux From Scratch /tools directory. It also produces a bootable Linux kernel for the target platform, and packages the /tools directory as a squashfs image for use by QEMU.
package-mini-native.sh: This script creates an ext2 filesystem image for use with qemu. It currently does this using a User Mode Linux image created by the host-tools.sh script.
sources/native/setup.sh: A test script to run inside the native environment. Mounts /proc and /sys, populates /dev, switches to a shell with command history, etc. (Not quite a substitute for a real init script, but something to play with.)
More to come...
Currently, host-tools.sh builds toybox and busybox 1.2.2. Eventually, toybox should completely replace busybox.
It creates symlinks to the host's compiler toolchain, specifically seven executalbes: ar, as, nm, cc, gcc, make, ld.
It also creates symlinks to a few utilities that need to be added to toybox. Currently, this list is: bzip2, find, install, od, sort, diff.
Note that until that last category is eliminated, rebuilding the system under itself requires natively building and installing the bzip2, coreutils, and diffutils packages as a bootstrapping step.
If you don't want to build the native toolchain, set the environment variable "BUILD_SHORT=1" before running the build. This results in a much, much smaller root filesystem, and also moves it up out of the /tools directory. But it eliminates
The default mini-native root filesystem is modeled after Linux From Scratch chapter 5. (This is why it lives in a /tools directory.)
BUILD_QUICK Not in /tools Adding packages (to the script, without the script) build/temp-$ARCH build/cross-compiler-$ARCH build/mini-native-$ARCH build/qemu-image-*.tarTo run a system on real hardware (not just under an emulator), you need to do several things:
Firmware Linux is licensed under GPL version 2. This means that the build scripts are licensed under GPL version 2, and each of the component packages of the default "mini-native" root filesystem may be redistributed under the terms of GPLv2 (and in the case of uClibc, LGPLv2).
Adding your own packages to the resulting system is generally "mere aggregation" (see the last paragraph of section 2), and thus not my problem. This license statement is not intended to apply to your packages as long as they are not derived works of existing GPLv2 code.