changeset 809:d326c68aa747

Update website and READMEs.
author Rob Landley <>
date Thu, 20 Aug 2009 22:48:42 -0500
parents cce6b8e81581
children 4cfa8c130605
files www/downloads/README www/downloads/binaries/README www/index.html www/news.html
diffstat 4 files changed, 381 insertions(+), 112 deletions(-) [+]
line wrap: on
line diff
--- a/www/downloads/README	Thu Aug 20 20:18:46 2009 -0500
+++ b/www/downloads/README	Thu Aug 20 22:48:42 2009 -0500
@@ -1,101 +1,96 @@
-A note about building old versions under Ubuntu 7.04 or later:
+The downloads directory contains the Firmware Linux build scripts, which is
+the source code for the FWL project.  If you would like to build your own
+cross compiler or target system image from source, use these build scripts.
+They're written in bash and should be fairly easy to read.
-  Ubuntu 7.04 broke the /bin/sh symlink to point to the Defective Annoying
-  Shell (dash), which can't run the FWL scripts.
-  FWL 0.2.2 and later work around this bug in Ubuntu by explicitly saying
-  #!/bin/bash at the start of each script.  To build older FWL versions
-  under new Ubuntu versions, you'll have to change the "#!/bin/sh" lines
-  at the start of each FWL script to say "#!/bin/bash" instead.
+If you want to download prebuilt binary cross compilers or system images,
+see the downloads/binaries directory (which has its own README).
-  Here's one way to do that:
-    sed -i 's@^#!/bin/sh$@#!/bin/bash@' *.sh
+These scripts include the following stages:
-  Other Linux distributions do not exhibit this bug.  (Even MacOS X has
-  /bin/sh point to bash, despite using a different login shell by default.)
+    Top level wrapper script, calls the others in sequence.  Requires one
+    argument, which is the target platform to build for.  When run without
+    arguments, it lists available architectures.
-  Also note that User Mode Linux 2.6.20 and earlier no longer build on a modern
-  system because the field aio_reserved3 went away in /usr/include.  (Yes, the
-  API exported to userspace, as used by Linux itself, is unstable.)  Attempts
-  to build older FWL versions need to either fix that, or skip building UML.
+    Several environment variables can be set to control its behavior, see
+    the file "configure" for details.
-  The oldest version that builds unmodified on an ubuntu 7.10 system is
-  FWL 0.3.0.  You can also install an older distro under qemu, and build the
-  older versions under that.  The Red Hat 9 image available from
- should build all the versions before 0.3.0.
+    You can invoke the other scripts in sequence if you like, but this is
+    generally the one you use to do everything else.
-Contents of the Firmware Linux download directory.
-Source tarballs:
+    Uses wget to download the source code required by the later build stages,
+    saving it in the "packages" directory.  It compares the sha1 checksum
+    of any existing tarballs to an expected value, only downloading new
+    source tarballs when it needs to.
-  The firmware-* tarballs contain build scripts which produce a uClibc-based
-  cross compiler and native build environment for various target platforms.
-  Run "./" to see a list of target platforms, and run "./ $ARCH"
-  to build for a given target platform.  Old versions of the build script
-  tarballs are there for historical reasons; the newest version is probably
-  always the one you want.
+    If the primary site is down, it checks a series of fallback mirrors.
+    The environment variable PREFERRED_MIRROR can insert a new mirror at
+    the start of the list, which is checked before even the official website.
+    This script is not target-specific, and only needs to be called once
+    when building multiple architectures.
-  The "binaries/cross-compiler" directory contains "host-i686" and "host-x86_64"
-  directories which contain prebuilt cross compilers which run on the
-  appropriate type of host.  The i686 versions were built under Ubuntu 6.06 and
-  the x86_64 versions were built under Ubuntu 7.04.  Each was built using the
-  newest release version of the build scripts, and when you run the build
-  yourself these tarballs should be created in the "build" directory.
+    Sanitizes the host environment by building known versions of needed tools
+    from source code, then restricting the $PATH to just those tools.  This is
+    an optional step which can be skipped, but without it the build process
+    is very brittle.
-  Each cross-compiler-$ARCH tarball contains a compiler toolchain which
-  produces binaries or the given platform, linked against uClibc.  (If you
-  just want to build uClibc binaries on an x86 host, use the toolchain in
-  binaries/cross-compiler/host-i686/cross-compiler-i686.tar.bz2.)
+    This step serves a similar purpose to the temporary system built by Linux
+    From Scratch's chapter 5, isolating the new system from variations in the
+    host.  It also acts as an early check that the resulting system images
+    offer a sufficient development environment to rebuild themselves from
+    source, because the host tool versions used to build them in the first
+    place are the same ones the scripts install into the target root filesystem.
+    This script populates the "build/host" directory, which is automatically
+    used by later stages if it exists.  It is not target specific, and only
+    needs to be run once when building multiple architectures.
-  To use one of these compilers, extract the tarball and use the "$ARCH-gcc"
-  binary as your compiler, which is located in the "bin" subdirectory.  You
-  might find it convenient to add that to your $PATH.  (All the headers and
-  libraries for the target are located relative to $ARCH-gcc, so you can
-  extract the tarball anywhere you like, and move the directory it creates
-  anywhere, but don't move stuff around within that directory.)
+    Creates a cross compiler for the selected target architecture, built from
+    gcc, binutils, uClibc, and the Linux kernel headers.
-  Note: This cross compiler is small and simple and only supports C.  The
-  native compiler in mini-native supports C++ as well.
+    The resulting compiler is assembled in build/cross-compiler-ARCH and
+    then packaged as an adjacent tarball of the same name.
-  Each mini-native-$ARCH tarball contains a minimal native root filesystem
-  for the given platform.  This filesystem is organized as a Linux From
-  Scratch style /tools directory containing uClibc, a compiler, and basic
-  system tools (mostly busybox), designed to boot with the kernel arguments
-  "init=/tools/bin/sh PATH=/tools/bin".
+    Creates a root filesystem mfor the target, built from busybox and
+    uClibc.  Adds to it a native compiler built from the same packages as
+    the cross compiler, plus the packages make, bash, and distcc.
-  This filesystem contains a native version of gcc, which builds stuff relative
-  to / (not to /tools), so in order to run the compiled programs either symlink
-  /lib to /tools/lib, start by building and installing uClibc, or statically
-  link the programs you build.  For more information, see
+    This step uses the cross compiler built in the previous step.  It
+    assembles the new filesystem in the build/root-filesystem-ARCH directory,
+    then packages it as an adjacent tarball of the same name.
-  This directory contains tarballs with five files per target architecture:
+    Package up the root filesystem into a filesystem image (ext2, squashfs,
+    or initramfs), build a Linux kernel configured for the target, and
+    generate a wrapper script capable of invoking an appropriate emulator
+    (generally qemu).
-  image-$ARCH.ext2.bz2: a bzipped ext2 filesystem image containing the
-  files from the corresponding mini-native tarball.  Run bunzip2 on this before
-  using it.
+    The system images are generated in build/system-image-ARCH directory,
+    and packaged as a tarball of the same name.
-  zImage-$ARCH: a bootable Linux kernel configured for use with QEMU.
- shell script that attempts to boot the corresponding ext2
-  filesystem image and Linux kernel zImage files under the emulator QEMU
-  (version 0.9.1 or newer).  The script expects to find both files in the
-  current directory.
+    Boot up a system image under its emulator, with full native development
+    environment options (a 2 gigabyte /dev/hdb mounted on /home and distcc
+    calling out to the appropriate cross compiler).
- shell script that creates an empty 2 gigabyte ext2 image
-  named hdb.img, to act as a second hard drive for the emulator to mount on
-  /home.  It then calls  (It will not recreate the image if it
-  already exists.)
+    Note that targets with the hw- prefix are aimed at actual hardware, and do
+    not have an emulator configured.  Hardware targets are derived from an
+    existing architecture, repackaging the other architecture's root filesystem
+    with a different Linux kernel configuration.
- a shell script that runs a distcc server hooked up to
-  the cross compiler for this architecture, and calls with
-  extra environment variables so the development environment inside the
-  emulator can call out to the cross compiler for extra speed.
+The wrapper script runs on every available target,
+with extra configure options to produce additional optional stages such as
+statically linked cross and native compilers.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/www/downloads/binaries/README	Thu Aug 20 22:48:42 2009 -0500
@@ -0,0 +1,58 @@
+The downloads/binaries directory contains prebuilt binary images, created by
+running ./ in the most recent Firmware Linux source tarball.  The
+source packages for these binaries are mirrored at
+The following tarballs are found here:
+  Statically linked cross compilers which creates target binaries for
+  a given architecture (linked against uClibc).
+  To use, extract this tarball and add its "bin" subdirectory to your $PATH,
+  then use the appropriate ARCH-gcc as your compiler name.
+  Same as the above cross-compiler tarballs, only built to run on an i686
+  host and statically linked (against uClibc, this time on the host) for
+  maximum portability between PC Linux distributions.
+  These versions include uClibc++, to support C++.  Note that the i686 and
+  x86_64 targeted cross compilers allow you to build binaries linked against
+  uClibc/uClibc++ with minimal preparation.
+  Native Linux root filesystem for a given target, suitable for chrooting into
+  (on appropriate hardware) or packaging up into a bootable system image.  It
+  contains busybox, uClibc, a simple boot script (usr/sbin/, and a
+  native toolchain with which to build additional target binaries from source.
+  Statically linked version of the native compiler from root-filesystem,
+  which you can extract and run on an appropriate target the same way you
+  can extract and run the cross-compiler on the host.
+  You don't need this when using FWL's root filesystem images, it provides
+  a native compiler for use with existing target filesystems.  Again,
+  linking binaries against uClibc/uClibc++.
+  Prepackaged bootable system images image for each target.
+  This includes the above root-filesystem files (packaged as either ext2 or
+  squashfs filesystem images), an appropriately configured Linux kernel,
+  and a wrapper script to invoke the emulator QEMU on them.  Running the
+  wrapper script should produce a shell prompt on the emulator's stdin/stdout
+  connected to the emulated system's /dev/console.
+  This allows you to compile additional packages natively, generally under
+  QEMU.  (Just wget the source tarball and build it normally.)  See the file
+  "" in the FWL source tarball for an example of how to set
+  up a working native development environment with a writeable 2 gigabyte
+  disk image (mounted on /home) and optionally use distcc to call out to the
+  cross compiler to accelerate the native builds.
--- a/www/index.html	Thu Aug 20 20:18:46 2009 -0500
+++ b/www/index.html	Thu Aug 20 22:48:42 2009 -0500
@@ -1,6 +1,6 @@
 <!--#include file="header.html" -->
-<h2><a href=news.html>News: 0.9.6 release April 2, 2009</a></h2>
+<h2><a href=news.html>News: 0.9.7 released August 20, 2009</a></h2>
 <b><h1><a href=documentation.html>What is Firmware Linux?</a></h1></b>
@@ -12,7 +12,7 @@
 Linux development environment for each target, runnable on real hardware or
 under emulators such as <a href=>QEMU</a>.</p>
-<p>Currently supported targets include arm, mips, powerpc, and x86, x86-64.
+<p>Currently supported targets include arm, mips, powerpc, x86, and x86-64.
 Partial support is available for sparc, sh4, and m68k.</p>
 <p>For more information, see <a href=documentation.html>the documentation
@@ -24,49 +24,30 @@
 <b><h2><a href=downloads>Source Code</a></h2></b>
 <p>The current source tarball is
-<a href=downloads/firmware-0.9.6.tar.bz2>Firmware Linux version 0.9.6</a>.
+<a href=downloads/firmware-0.9.7.tar.bz2>Firmware Linux version 0.9.7</a>.
 This is the series of shell scripts you run to create the various binary
 images.  See the <a href=downloads/README>README</a> for usage instructions,
 and the <a href=news.html>release notes</a>.</p>
 <p>Several <a href=downloads/binaries>prebuilt binary images</a>
-are available, based on the current Firmware Linux release.</p>
-<b><h2><a href=downloads/binaries/system-image>System Images</a></h2></b>
-<p>System images provide a complete native development environment, based
-on seven packages: Linux, uClibc, BusyBox, binutils, gcc, make, and bash.
-(The build also uses the toybox, genext2fs, uClibc++, and distcc packages, but
-does not depend on them to achieve a self-hosting OS image.)</p>
+are available, based on the current Firmware Linux release.  The
+<a href=downloads/README>README</a> describes each tarball.  The
+release notes on the <a href=news.html>news page</a> explain recent
-<p>System image tarballs contain an ext2 root filesystem image and a kernel
-configured to boot under the emulator QEMU.  Use the "./"
-script to use qemu to emulate the appropriate target system, giving you a
-shell prompt within the native development environment.  (Type "exit" when
-<b><h2><a href=downloads/binaries/mini-native>Root filesystem tarballs</a></h2></b>
-<p>If you prefer to package your own filesystem images, or use QEMU's
-application emulation mode, you can download each target's root filesystem
-packaged in a tarball.</p>
-<b><h2><a href=downloads/binaries/cross-compiler>Cross compilers</h2></a></b>
-<p>Prebuilt binary cross compilers for use on <a href=downloads/binaries/cross-compiler/host-i686>i686</a> or <a href=downloads/binaries/cross-compiler/host-x86_64>x86-64</a> hosts.</p>
 <b><h1><a href=/hg/firmware>Development</a></h1></b>
 <p>The project maintains a <a href=/hg/firmware>development repository</a>
 using the Mercurial source control system.  This includes RSS feeds for
-<a href=>each checkin</a>
-and for <a href=>new releases</a>.</p>
+<a href=/hg/firmware/rss-log>each checkin</a>
+and for <a href=/hg/firmware/rss-tags>new releases</a>.</p>
 <p>Questions about Firmware Linux should be addressed to the project's
-<a href=>mailing
-list</a>, the IRC channel #firmware on  The project
-maintainer's <a href=/notes.html>blog</a> often includes notes about
+<a href=>mailing
+list</a>, or the IRC channel #firmware on  The project
+maintainer's <a href=>blog</a> often includes notes about
 ongoing Firmware Linux development.</p>
 <!--#include file="footer.html" -->
--- a/www/news.html	Thu Aug 20 20:18:46 2009 -0500
+++ b/www/news.html	Thu Aug 20 22:48:42 2009 -0500
@@ -1,6 +1,241 @@
 <!--#include file="header.html" -->
+<h2>August 20, 2009</h2>
+<p><a href=downloads/firmware-0.9.7.tar.bz2>Version 0.9.7</a> is out, a little
+over a month and a half late.  It's a larger update than usual, so the
+release notes are a bit long.</p>
+<p>This release is based on
+<a href=>mercurial version 807</a>
+of the build scripts,
+and includes <b>Linux</b> and <b>BusyBox 1.14.3</b>.
+No new uClibc release is out since last time.</p>
+<p>Lots of little bugs got fixed.  For example, this release should build on
+Fedora 11 (and any other platform that hasn't got "which" installed by
+default), and now supports distcc and ccache on the host (and will use them
+automatically if they are installed).</p>
+<h3><b>Changes to build stages: new root-filesystem, cross-static, and
+native-compiler tarballs, upgraded and</b></h3>
+<p>The old "mini-native" stage has been renamed "root-filesystem"
+(the same way package-mini-native became system-image last release).  The
+script names (and resulting tarballs) now indicate what each stage makes.
+So calls,,,
+and, in that order.</p>
+<p>Th old script is gone, with its functionality
+integrated into (which now builds i686 hosted static toolchains
+for each target by default).  This is implemented by two new environment
+variables triggering optional behavior: STATIC_CROSS_COMPILER_HOST
+<p>Setting STATIC_CROSS_COMPILER_HOST to an architecture name creates a
+cross compiler statically linked to run on that host (via a technique
+known as canadian cross compile).  For example, the invocation:</p>
+<p>BUILD_CROSS_COMPILER_HOST=i686 ./ armv4l</P>
+<p>Would create a tarball called "cross-static-armv4l.tar.bz2" which was
+built to run on an i686 host, and was statically linked (against uClibc)
+on that host to be distribution independent.</p>
+<p>Setting BUILD_STATIC_NATIVE_COMPILER to any non-empty value creates a
+native compiler for the target (packaged as native-compiler-$ARCH.tar.bz2),
+which is statically linked against uClibc so it can be extracted and run on
+just about any system of the appropriate type.  (So if you can get a Linux
+shell prompt and have enough storage and memory, you should be able to
+compile stuff.)</p>
+<p>The upgraded script runs on each
+target built.  (The script attempts to compile and run "hello
+world" natively within a system image under qemu, and indicates whether or
+not it worked via "pass" or "fail".)  Note that now
+autodetects which targets have been built (have system images in the build
+directory), and times out after 60 seconds so targets that hang
+will return failure eventually.</p>
+<h3><b>Squashfs 4.0 now the default system image type</b></h3>
+<p>The root filesystem image type is now squashfs by default.  (To change it set
+SYSIMAGE_TYPE to ext2 or initramfs, either in your environment or the file
+<p>This involved upgrading the userspace squashfs support package
+to the version 4.0 supported by the upstream kernel, and numerous small fixes
+to work with a read-only root filesystem (with writeable spaced mounted on
+/home and /tmp).</p>
+<h3><b>Target upgrades</b></h3>
+<h3><b>ARM upgrades</b></h3>
+<p>Lots of work on the arm targets, with the addition of a new armv6l target
+and conversion of the armv5l target to
+<a href=>ARM EABI</a> (which used to be documented <a href=>here</a>,
+but ARM screwed up its website and now you have to go
+<a href=>here</a>).  The armv4l target still provides an ARM v4
+little endian soft float OABI target (which is "the i386 of ARM", meaning it
+should run on just about any arm hardware, if a bit slowly).  A new
+armv4be target is the same as armv4l except big endian.</p>
+<p>A new hw-tct-hammer target supports the <a href=>Tin Can Tools hammer/nail board</a>.</p>
+<h3><b>Updated sparc support, almost works now.  (uClibc for sparc still sucks.)</b></h3>
+<p>The sparc target has also been upgraded to the point where it now gives
+a shell prompt.  (And immediately dies with a bus error or a hang if you try
+to do anything, because uClibc for sparc still doesn't work.  The "upgrade"
+consisted of statically linking everything because uClibc's dynamic loader
+doesn't work for sparc.)</p>
+<h3><b>PowerPC remains fiddly due to QEMU issues, new powerpc-440fp target</b></h3>
+<p>PowerPC support in QEMU is
+<a href=>officially unstable</a>, so although FWL's powerpc target hasn't significantly
+changed from last release, the version of QEMU in source control no longer
+runs it (nor the binary powerpc system images released with FWL 0.9.6) and
+QEMU's developers do not consider this a regression.  While we search for a new
+Linux kernel .config that matches QEMU's current expectations (and await a
+release considered "stable"), note that setting HOST_BUILD_EXTRA=1 before
+running will build a version of qemu that does run powerpc and
+put it in build/host where can find it.  (Note also that
+building qemu from source still takes significantly longer than the rest of the stage combined.)</p>
+<p>A new powerpc-440fp target produces code for the powerpc 440 with hardware
+floating point.  (Theoretically QEMU's "bamboo" board emulation should
+run this, but QEMU doesn't emulate a 440 processor yet.  We compromise by
+running a ppc440 filesystem under qemu's power mac emulation, to take
+advantage of the ppc440 instruction set being almost a subset of full powerpc.
+This gets us a shell prompt, but throws illegal instruction errors if you
+try to do anything fancy.)</p>
+<p>(Note that powerpc-440fp is not a hw-target for powerpc, it's a different
+processor instruction set like i586 vs i686.  Alas, one that qemu doesn't
+properly emulate yet.)</p>
+<h3><b>Now using last GPLv2 release of GCC, and future plans</b></h3>
+<p>The upgrade to <b>gcc 4.2.1</b> gives us
+<a href=>the last
+GPLv2 licensed version of gcc</a> (thus avoiding
+<a href=>various problems</a>).
+<a href=>Make 3.81</a>
+was already the last GPLv2 release of that project.</p>
+<p>Note that <b>bash 2.05b</b> is still intentionally ancient (to avoid the
+bloat of 3.x), and may be replaced with busybox ash as the default FWL shell
+in a future release.  Similarly, although <b>binutils 2.17</b> was the last
+GPLv2 version from the FSF, an upgrade to
+<a href=>the
+last GPLv2 release of Red Hat's binutils fork,</a> is under
+consideration for a future release.  But mostly the GNU compiler toolchain
+has been upgraded as far as possible for the forseeable future, either because
+new versions provide no significant benefits or because they're not available
+under a license compatible with the Linux kernel's.</p>
+<p>Future upgrades to these packages will either be via individual patches
+(maintaining GPLv2 license) or by investigating alternative non-FSF
+packages such as OpenBSD's <a href=>PCC</a> or
+Apple's <a href=>LLVM</a>.  In preparation for support of
+alternate compilers, the build scripts have moved from using "gcc" to the
+more generic "cc" for the compiler name wherever possible, but currently no
+drop-in replacement compiler is available.</p>
+<h3><b>Implementation details</b></h3>
+<p>Each target configuration renamed "details" to "settings", and added
+a "description".  (This makes Gentoo From Scratch's kconfig easier.)</p>
+<p>The stage now populates a "packages" directory instead of
+"sources/packages", meaning that everything in the sources directory now
+comes from the FWL source tarball.  To do the equivalent of "make clean"
+you can "rm -rf build", and to do a "make distclean" you can
+"rm -rf packages build".</p>
+<p>The build no longer deletes the alt-* tarballs when UNSTABLE isn't
+set, you must do that by hand if you want an updated alt- version of a
+package.  The packages/MANIFEST file creation can now use the extended
+tarball information to detect git version numbers.</p>
+<p>The === bars now show the current stage name and architecture each
+package is being built for.  (Pipe the build output to grep "^===" to see
+just the start of each new package build.)  The same information is sent
+to the title bar of your xterm, export NO_TITLE_BAR=1 if you don't want the
+build to update the title bar.</p>
+<p>The BUILD_STATIC option now applies to all packages built in, and can be set from a target configuration's settings file
+(as sparc is now doing).</p>
+<p>The BUILD_VERBOSE option passes V=1 to the linux, busybox, and uClibc
+builds that otherwise sanitize their output.</p>
+<p>You can now set NATIVE_TOOLCHAIN=only to build just the compiler
+and not the other parts (busybox, make, toybox, bash...)  This is used
+by the canadian cross steps in to create static cross and native
+<p>This release broke up scripts/ so that script just
+sets lots of environment variables, and now includes scripts/
+to define shell functions.  The architecture setup (reading architecture
+files and creating temporary directories and such) is now done via the
+"read_arch_dir $ARCH" shell function, so merely including sources/
+should no longer have significant side effects.  Similarly, setupfor now
+has an EXTRACT_ONLY environment variable instead of depending on a blank
+$ARCH (which has, despite wanting to snapshot source so it can
+build stuff).</p>
+<p>Various fixes to make parallel builds work better.  (So it neither leaves
+background processes running nor kills the parent shell and closes your
+xterm when you hit ctrl-c.)  The new "killtree" shell function,
+which kills a process and all its children and grandchildren recursively with
+pgrep.  We also build our own sources/toys/mysetsid.c program with the host
+compiler (because the normal command line "setsid" doesn't also do a tcsetpgrp
+on stdin so signal handling isn't forwarded to the new session).  This should
+more reliably allow ctrl-c to exit and and such,
+and let FORK=1 ./ stop all its background processes when
+interrupted.  (Note that also honors FORK=1.)</p>
+<p>The logs from now live in build/logs.</p>
+<p>The new config option ROOT_NODIRS avoids creating the normal set of empty
+directories in the new root filesystem.  (The old /tools support went
+away, but a BUILD_STATIC ROOT_NODIRS build can be extracted into /tools
+and used from there.  Then either symlink "/lib" to "/tools/lib" or "export
+UCLIBC_DYNAMIC_LINKER=/tools/lib/" to add more stuff to
+/tools natively.)</p>
+<p>The compiler wrapper (sources/toys/ccwrap.c) can now use
+architecture-specific WRAPPER_TOPDIR values.  (I.E. armv4l-cc could
+"export armv4l_WRAPPER_TOPDIR=/path/to/directory".)  This makes
+canadian cross compiles a lot easier.</p>
 <h2>April 2, 2009</h2>
 <p><a href=downloads/firmware-0.9.6.tar.bz2>Version 0.9.6</a> includes
 Linux 2.6.29 and uClibc, now with support for sh4 and upgraded powerpc