--- a/www/README	Wed May 05 22:14:47 2010 -0500
+++ b/www/README	Wed May 05 22:15:24 2010 -0500
@@ -18,6 +18,24 @@
   to speed up the build without reqiring the packages you're building to
   know anything about cross compiling.
 
+--- How do I try it out?  (Quick start.)
+
+  - Download a system-image tarball for a target that interests you.
+
+  - Extract it and cd into the directory.
+
+  - Run the "./run-emulator.sh" script.
+
+    After the kernel boot messages and the output of the init script, you
+    should get a shell prompt from inside the emulator.
+
+    - Run "cat /proc/cpuinfo" to confirm the emulator is running.
+
+    - Run "gcc -lpthread /usr/src/thread-hello2.c" (and run the resulting
+      "./aout" file) to confirm the native toolchain works.
+
+    - Type "exit" when done.
+
 --- What's this "target/host" business?
 
   The host is the system the emulator runs on.  The target is the virtual
@@ -62,22 +80,23 @@
     http://aboriginal.impactlinux.com/downloads/binaries
 
   The "system-image" tarballs are what you need to boot a virtual target
-  under QEMU, they have a squashfs root filesystem.  The "rw-system-image"
-  tarballs are the same thing with an ext2 root filesystem, which lets you
-  write to it.  (So you can upgrade those, but they're easier to screw
+  under QEMU.  They contain a squashfs root filesystem (including a native
+  compiler toolchain), an appropriately configured Linux kernel, and shell
+  scripts to invoke the the emulator with appropriate arguments.
 
   The cross-compiler tarballs are useful for accelerating native builds via
-  distcc (explained later in this file). 
+  distcc (using the dev-environment.sh script, explained later in this file).
 
-  If you want to install on real hardware (or set up a chroot), the
-  root-filesystem and native-compiler tarballs are probably what you want.
+  If you want to install Aboriginal Linux on real hardware (or set up a
+  chroot), the root-filesystem and native-compiler tarballs are probably
+  what you want.  (You may need to provide your own kernel and bootloader.)
 
   Various statically linked binaries are also available for each target
   (busybox, dropbear, strace...) which can be used on any appropriate target,
   not just with Aboriginal Linux.  Just download them (with wget), set the
   executable bit (chmod +x), and run them normally.
 
-To use the build scripts to build your own binaries:
+To use the build scripts to build your own binaries from source:
 
   Download the most recent set of build scripts from:
 
@@ -94,7 +113,7 @@
 
       http://aboriginal.impactlinux.com/snapshots
 
-  To build everything for a target from source:
+  To compile a system image (and all prerequisite stages) for a target:
 
       ./build.sh mipsel
 
@@ -109,26 +128,8 @@
     in this case build/system-image-mipsel (with a corresponding tarball
     version for posterity).
 
-  The build.sh script is a wrapper around other scripts, which can be run
-  individually.  The main three are:
-
-      simple-cross-compiler.sh - create a cross compiler for the target.
-
-      root-filesystem.sh - use the cross compiler to build a root filesystem.
-
-      system-image.sh - build a kernel and ext2 image to run under emulator.
-
-    An optional (but often useful) fourth script is:
-
-      native-compiler.sh - create a more complicated compiler for the target,
-                           statically linked against uClibc and with thread
-                           support and uClibc++.  (This can also be used
-                           to create a better cross compiler, with support for
-                           threading and C++, but that's not necessary to build
-                           a root filesystem or system image.)
-
-  If you'd like to build every target simultaneously (in parallel, which needs
-  about 2 gigabytes of ram):
+  To build every supported target simultaneously (in parallel, using around
+  2 gigabytes of ram and maybe 20 gigabytes of disk space):
 
     FORK=1 sources/more/buildall.sh
 
@@ -137,12 +138,9 @@
   the all doo.  (You can persistently set them by altering this file, or
   set them temporarily in your environment before running a build.)
 
-  The equivalent of "make clean" is "rm -rf build".  The equivalent of
-  "make distclean" is "rm -rf build packages".
+  For more information, see the README file in the download directory.
 
-  For more information on implementation details:
-
-      http://aboriginal.impactlinux.com/implementation.html
+    http://aboriginal.impactlinux.com/downloads/README
 
 To boot a system image under QEMU:
 

--- a/www/downloads/README	Wed May 05 22:14:47 2010 -0500
+++ b/www/downloads/README	Wed May 05 22:15:24 2010 -0500
@@ -1,7 +1,7 @@
-The downloads directory contains the Aboriginal Linux build scripts, which is
-the source code for the Aboriginal Linux 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.
+The Aboriginal Linux build scripts are the source code for the Aboriginal
+Linux 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.
 
 If you want to download prebuilt binary cross compilers or system images,
 see the downloads/binaries directory (which has its own README).  The
@@ -11,9 +11,12 @@
 
   build.sh ARCH
 
-    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.
+    Top level wrapper script, calls the others scripts in sequence:
+    download.sh, host-tools.sh, simple-cross-compiler.sh, native-compiler.sh,
+    root-filesystem.sh, and system-image.sh.
+
+    It requires one argument, which is the target platform to build for.
+    When run without arguments, build.sh lists available architectures.
 
     Several environment variables can be set to control its behavior, see
     the file "configure" for details.
@@ -42,11 +45,11 @@
     an optional step which can be skipped, but without it the build process
     is very brittle.
 
-    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
+    This "airlock" 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
@@ -62,34 +65,35 @@
     and then packaged as an adjacent tarball of the same name.
 
     (This compiler is sufficient to build a system image for the target, but
-    isn't as powerful as the compilers created by native-compiler.sh.)
+    isn't as powerful as the compilers created by native-compiler.sh.  It
+    doesn't include thread support, uClibc++, or the shared version of libgcc.)
 
   native-compiler.sh ARCH
 
-    This (optional) step creates an additional compiler for the selected
-    target, using one or more of the existing simple cross compilers.  It
-    can create a purely native compiler (which runs on the target to produce
-    target code), or it can create a more complicated cross compiler
-    (statically linked against uClibc, with thread support and uClibc++)
-    using two simple cross compilers (one for the host, one for the target).
+    This (optional) step creates a compiler for the selected target, using one
+    or more of the existing simple cross compilers.  It can create a purely
+    native compiler, which runs on the target to produce target code.
+
+    By default this compiler is statically linked so you can add it to an
+    existing target root filesystem.  Use BUILD_STATIC=none to disable this.
+
+    This script can also create a portable cross compiler (statically linked
+    against uClibc on the host) by using two simple cross compilers (one for
+    the host, one for the target) to implement a build technique called
+    "canadian cross".  This can be extracted an run on an arbitrary (x86
+    or x86-64) host.
+
     See build.sh and the config options STATIC_CC_HOST and NO_NATIVE_COMPILER
     for details.
 
   root-filesystem.sh ARCH
 
-    Creates a root filesystem for the target, built from busybox/toybox and
-    uClibc.
+    Creates a root filesystem for the target, built from busybox and uClibc.
 
     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.
 
-    If a native compiler exists for the target (I.E. the native-compiler.sh
-    script was run, which build.sh will do if the environment variable
-    NO_NATIVE_COMPILER is not set), it adds that to the root filesystem and
-    builds the packages make, bash, and distcc to provide a native build
-    environment.
-
   system-image.sh ARCH
 
     Package up the root filesystem into a filesystem image (ext2, squashfs,
@@ -100,6 +104,10 @@
     The system images are generated in build/system-image-ARCH directory,
     and packaged as a tarball of the same name.
 
+    Note: the native-compiler and root-filesystem stages are built and tarred
+    up separately, but build.sh will install native-compiler into the
+    root-filesystem before calling system-image.sh.
+
   run-from-build.sh ARCH
 
     Boot up a system image under its emulator, with full native development
@@ -111,6 +119,9 @@
     existing architecture, repackaging the other architecture's root filesystem
     with a different Linux kernel configuration.
 
+  The equivalent of "make clean" is "rm -rf build".  The equivalent of
+  "make distclean" is "rm -rf build packages".
+
 The sources/more directory contains additional scripts providing additonal
 functionality not called from build.sh.