changeset 1048:f969c1ec66f4

Move README into the www directory, where it can be linked from the the website.
author Rob Landley <rob@landley.net>
date Sun, 02 May 2010 16:16:11 -0500
parents d98aa02a7edf
children 0e063506fd67
files README www/README
diffstat 2 files changed, 281 insertions(+), 281 deletions(-) [+]
line wrap: on
line diff
--- a/README	Sun May 02 16:15:08 2010 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,281 +0,0 @@
-Aboriginal Linux: We cross compile so you don't have to.
-
-===============================================================================
---- What is it?
-
-  Aboriginal Linux provides virtual Linux images you can boot under QEMU,
-  within which you can compile and test any software you like.
-
-  The build scripts automatically create cross compilers and bootable system
-  images for various targets, such as arm, mips, powerpc, and x86.  You can
-  download the resulting binaries from the website if you don't want to bother
-  compiling them yourself.
-
-  The system images provide minimal native development environments which you
-  can boot under an emulator (or on real hardware if you have it) to compile
-  code natively.  This includes a full native compiler (for both C and C++),
-  and the (optional) ability to run the cross compiler on the host (via distcc)
-  to speed up the build without reqiring the packages you're building to
-  know anything about cross compiling.
-
---- What's this "target/host" business?
-
-  The host is the system the emulator runs on.  The target is the virtual
-  system running inside the emulator.
-
---- Do I have to care about cross compiling?
-
-  No, you don't.  Just boot a system image under QEMU and build packages in
-  there (or find some real hardware to boot your root filesystem on, and note
-  that the distcc acceleration trick still works in that context too).
-
-===============================================================================
---- What's the purpose of this project?
-
-  Aboriginal Linux serves two purposes: practical and educational.
-
-  The practical purpose is to provide emulated native development environments
-  for every target QEMU supports.  This avoids the need for cross compiling
-  by allowing you to download a bootable system image and build natively within
-  it.
-
-  Aboriginal Linux is also designed to document how to bootstrap minimal
-  Linux development environments for a new target.  The build is a series of
-  bash scripts, with lots of comments explaining what they do.  These scripts
-  show how to make a cross compiler (and optionally how to use it to make
-  a better cross compiler), how to build a root filesystem and native
-  development tools, and how to package and boot the result under an emulator.
-  If you don't know how something works, read the script.  If something's
-  unclear, ask about it on the mailing list.
-
---- How does it work?
-
-  For information on implementation details:
-
-      http://aboriginal.impactlinux.com/implementation.html
-
-===============================================================================
---- How do I use Aboriginal Linux?
-
-To download prebuilt binaries for each target:
-
-    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
-
-  The cross-compiler tarballs are useful for accelerating native builds via
-  distcc (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.
-
-  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:
-
-  Download the most recent set of build scripts from:
-
-      http://aboriginal.impactlinux.com/downloads
-
-  To list available targets, do:
-
-      ./build.sh
-
-    We'll use "mipsel" (mips little endian) in the following examples.  Replace
-    that with the target you're interested in from this list.
-
-    For more information about each target, see:
-
-      http://aboriginal.impactlinux.com/snapshots
-
-  To build everything for a target from source:
-
-      ./build.sh mipsel
-
-    This calls the other stages (from download.sh through system-image.sh)
-    in order, to produce a bootable system image.  The downloaded source
-    tarballs are kept in the "packages" directory, all other output goes into
-    the "build" directory.
-
-    For each target, the build tars up the various build stages
-    (cross compiler, native compiler, root filesystem, etc).  The last stage
-    is a bootable system image configured for use with the emulator QEMU,
-    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):
-
-    FORK=1 sources/more/buildall.sh
-
-  The file "configure" contains several environment variables you can set to
-  control the behavior of Aboriginal Linux, and has comments documenting what
-  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 on implementation details:
-
-      http://aboriginal.impactlinux.com/implementation.html
-
-To boot a system image under QEMU:
-
-    cd build/system-image-mipsel
-    ./run-emulator.sh
-
-  Each system image contains a root filesystem image (for use as a virtual
-  hard drive), a kernel configured for use with QEMU, and a run-emulator.sh
-  shell script to boot those two files together under QEMU.
-
-  After the kernel boot messages scroll by, you should have a shell prompt
-  inside qemu.  Try "cat /proc/cpuinfo" to confirm it's not the same as your
-  host.  Try "cc /usr/src/hello.c" to build some of the included example
-  code.  Type "exit" to shut it down.
-
-  The environment variable QEMU_EXTRA can supply extra command line arguments
-  to the emulator.  The environment variable KERNEL_EXTRA can supply extra
-  command line arguments to the Linux kernel running under the emulator.
-
-To set up a more powerful virtual build environment:
-
-    cd build/system-image-mipsel
-    ./dev-environment.sh
-
-  The dev-environment.sh script is a wrapper around run-emulator.sh that does
-  two things to give you a better development environment:
-
-  1) Make sure the emulator allocates at least 256 megs of physical memory.
-
-     Set the environment variable QEMU_MEMORY to the desired number of
-     megabytes if you'd like more.  (Note that some targets can't support more
-     than this, in which case the emulator will print out an error message
-     instead of launching the virtual system.)
-
-  2) Mount lots of writeable space on /home in the virtual system.
-
-     The script creates a 2 gigabyte sparse file on the host named hdb.img,
-     formats it ext3, and tells the emulator to mount it on /home.
-
-     This keeps the existing hdb.img if it already exists, so its contents
-     persist between dev-environment.sh invocations.  If you need more space
-     than 2 gigabytes, you can supply your own hdb.img.
-
-  2) Hook up distcc to call out to the cross compiler on the host, to speed
-     up your builds by moving the heavy lifting of compilation outside the
-     emulator.
-
-     This only happens if you have both distccd and the appropriate cross
-     compiler is in your host system's $PATH.  (Install distcc on the host,
-     and downloaded the appropriate cross compiler tarball and add its "bin"
-     subdirectory to your $PATH).  If both are available, the script launches
-     a private instance of distccd and configures the virtual system to use
-     distcc to call out to the cross compiler.
-
-     The reason this doesn't re-introduce the complexity of cross compiling is
-     because the build still only has a single context, and thus behaves like
-     a fully native build.  Configure, make, preprocessing, and linking all
-     still run natively inside the emulator.  Using distcc means the build
-     sends preprocessed source out through the network and gets compiled .o
-     files back, but it neither knows nor cares whether the servers it's
-     connecting to are cross compiling or native compiling, as long as they
-     produce the right output.
-
-To automatically build more software packages inside the emulator:
-
-    ./native-build.sh mipsel hello-world.hdc output_dir
-
-  Aboriginal Linux supports automated builds via a two stage process.
-  Get a control image, then launch a system image with it.
-
-  1) Obtain a control image.
-
-     The scripts in sources/native-build (such as hello-world.sh and
-     static-tools.sh) create build control filesystem images.  For example,
-
-       sources/native-build/hello-world.sh hello-world.hdc
-
-     These are squashfs formatted filesystem images that contain extracted
-     source code, plus a shell script to build that code and upload it to
-     the host (via ftp).
-
-     You're encouraged to create your own control images using the existing
-     native-build scripts as a model.  The images the existing scripts create
-     are available in the downloads/binaries directory.
-
-  2) Use native-build.sh to launch that control image under the emulator.
-
-     This is another wrapper script, this time around dev-environment.sh
-     (which is in turn a wrapper script around run-emulator.sh).
-
-     This wrapper does two things:
-
-     1) Launch an ftp daemon, and inform the virtual system where to find it
-        via the FTP_HOST and FTP_PORT environment variables.  This lets the
-        emulated target system upload files to the host via "ftpput".
-
-        Launching an FTP daemon requires busybox in the $PATH on the host, and
-        uses the busybox nc and ftpd applets to provide an ftp server.  (We
-        can't use an arbitrary one on the host because different ftp daemons
-        understand different command line options.)
-
-        You can set the environment variables $FTP_HOST and $FTP_PORT to point
-        it at an existing FTP daemon.  If either variable is set, the script
-        won't launch a new FTP daemon.  (Note that the default value for
-        $FTP_HOST is 10.0.2.2, which is QEMU's tunnel through to the host
-        system's 127.0.0.1.)
-
-     2) Launch the emulated development environment with a control image, to
-        be mounted on /mnt by the init script.
-
-        Basically this adds "-hdc filename" to the QEMU_EXTRA environment
-        variable to supply a third virtual disk to the emulator, then calls
-        ./dev-environment.sh as normal.
-
-        The Aboriginal Linux init script (sbin/init.sh) checks for the
-        existence of /mnt/init, and runs that if it exists instead of
-        providing an interactive shell prompt.  (It waits three seconds for
-        you to press a key if you do want a shell prompt, in which case you
-        can launch /mnt/init yourself when you're done.)
-
-        When /mnt/init exits, the virtual system shuts down and exits the
-        emulator, just like typing "exit" at the interactive shell prompt.
-
-To cross compile stuff on the host:
-
-  If you already do cross compiling, and would like to use this project's cross
-  compiler to build something else, just add its "bin" subdirectory to the
-  $PATH, and use the build tools prefixed with the target name:
-
-    PATH=$(pwd)/build/cross-compiler-mipsel/bin:$PATH
-    mipsel-gcc -static hello.c -o hello
-    qemu-mipsel hello
-
-  If you don't do cross compiling already, this project isn't going to teach
-  you how, and in fact recommends you just don't go there.  We cross compile
-  so you don't have to.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/www/README	Sun May 02 16:16:11 2010 -0500
@@ -0,0 +1,281 @@
+Aboriginal Linux: We cross compile so you don't have to.
+
+===============================================================================
+--- What is it?
+
+  Aboriginal Linux provides virtual Linux images you can boot under QEMU,
+  within which you can compile and test any software you like.
+
+  The build scripts automatically create cross compilers and bootable system
+  images for various targets, such as arm, mips, powerpc, and x86.  You can
+  download the resulting binaries from the website if you don't want to bother
+  compiling them yourself.
+
+  The system images provide minimal native development environments which you
+  can boot under an emulator (or on real hardware if you have it) to compile
+  code natively.  This includes a full native compiler (for both C and C++),
+  and the (optional) ability to run the cross compiler on the host (via distcc)
+  to speed up the build without reqiring the packages you're building to
+  know anything about cross compiling.
+
+--- What's this "target/host" business?
+
+  The host is the system the emulator runs on.  The target is the virtual
+  system running inside the emulator.
+
+--- Do I have to care about cross compiling?
+
+  No, you don't.  Just boot a system image under QEMU and build packages in
+  there (or find some real hardware to boot your root filesystem on, and note
+  that the distcc acceleration trick still works in that context too).
+
+===============================================================================
+--- What's the purpose of this project?
+
+  Aboriginal Linux serves two purposes: practical and educational.
+
+  The practical purpose is to provide emulated native development environments
+  for every target QEMU supports.  This avoids the need for cross compiling
+  by allowing you to download a bootable system image and build natively within
+  it.
+
+  Aboriginal Linux is also designed to document how to bootstrap minimal
+  Linux development environments for a new target.  The build is a series of
+  bash scripts, with lots of comments explaining what they do.  These scripts
+  show how to make a cross compiler (and optionally how to use it to make
+  a better cross compiler), how to build a root filesystem and native
+  development tools, and how to package and boot the result under an emulator.
+  If you don't know how something works, read the script.  If something's
+  unclear, ask about it on the mailing list.
+
+--- How does it work?
+
+  For information on implementation details:
+
+      http://aboriginal.impactlinux.com/implementation.html
+
+===============================================================================
+--- How do I use Aboriginal Linux?
+
+To download prebuilt binaries for each target:
+
+    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
+
+  The cross-compiler tarballs are useful for accelerating native builds via
+  distcc (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.
+
+  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:
+
+  Download the most recent set of build scripts from:
+
+      http://aboriginal.impactlinux.com/downloads
+
+  To list available targets, do:
+
+      ./build.sh
+
+    We'll use "mipsel" (mips little endian) in the following examples.  Replace
+    that with the target you're interested in from this list.
+
+    For more information about each target, see:
+
+      http://aboriginal.impactlinux.com/snapshots
+
+  To build everything for a target from source:
+
+      ./build.sh mipsel
+
+    This calls the other stages (from download.sh through system-image.sh)
+    in order, to produce a bootable system image.  The downloaded source
+    tarballs are kept in the "packages" directory, all other output goes into
+    the "build" directory.
+
+    For each target, the build tars up the various build stages
+    (cross compiler, native compiler, root filesystem, etc).  The last stage
+    is a bootable system image configured for use with the emulator QEMU,
+    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):
+
+    FORK=1 sources/more/buildall.sh
+
+  The file "configure" contains several environment variables you can set to
+  control the behavior of Aboriginal Linux, and has comments documenting what
+  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 on implementation details:
+
+      http://aboriginal.impactlinux.com/implementation.html
+
+To boot a system image under QEMU:
+
+    cd build/system-image-mipsel
+    ./run-emulator.sh
+
+  Each system image contains a root filesystem image (for use as a virtual
+  hard drive), a kernel configured for use with QEMU, and a run-emulator.sh
+  shell script to boot those two files together under QEMU.
+
+  After the kernel boot messages scroll by, you should have a shell prompt
+  inside qemu.  Try "cat /proc/cpuinfo" to confirm it's not the same as your
+  host.  Try "cc /usr/src/hello.c" to build some of the included example
+  code.  Type "exit" to shut it down.
+
+  The environment variable QEMU_EXTRA can supply extra command line arguments
+  to the emulator.  The environment variable KERNEL_EXTRA can supply extra
+  command line arguments to the Linux kernel running under the emulator.
+
+To set up a more powerful virtual build environment:
+
+    cd build/system-image-mipsel
+    ./dev-environment.sh
+
+  The dev-environment.sh script is a wrapper around run-emulator.sh that does
+  two things to give you a better development environment:
+
+  1) Make sure the emulator allocates at least 256 megs of physical memory.
+
+     Set the environment variable QEMU_MEMORY to the desired number of
+     megabytes if you'd like more.  (Note that some targets can't support more
+     than this, in which case the emulator will print out an error message
+     instead of launching the virtual system.)
+
+  2) Mount lots of writeable space on /home in the virtual system.
+
+     The script creates a 2 gigabyte sparse file on the host named hdb.img,
+     formats it ext3, and tells the emulator to mount it on /home.
+
+     This keeps the existing hdb.img if it already exists, so its contents
+     persist between dev-environment.sh invocations.  If you need more space
+     than 2 gigabytes, you can supply your own hdb.img.
+
+  2) Hook up distcc to call out to the cross compiler on the host, to speed
+     up your builds by moving the heavy lifting of compilation outside the
+     emulator.
+
+     This only happens if you have both distccd and the appropriate cross
+     compiler is in your host system's $PATH.  (Install distcc on the host,
+     and downloaded the appropriate cross compiler tarball and add its "bin"
+     subdirectory to your $PATH).  If both are available, the script launches
+     a private instance of distccd and configures the virtual system to use
+     distcc to call out to the cross compiler.
+
+     The reason this doesn't re-introduce the complexity of cross compiling is
+     because the build still only has a single context, and thus behaves like
+     a fully native build.  Configure, make, preprocessing, and linking all
+     still run natively inside the emulator.  Using distcc means the build
+     sends preprocessed source out through the network and gets compiled .o
+     files back, but it neither knows nor cares whether the servers it's
+     connecting to are cross compiling or native compiling, as long as they
+     produce the right output.
+
+To automatically build more software packages inside the emulator:
+
+    ./native-build.sh mipsel hello-world.hdc output_dir
+
+  Aboriginal Linux supports automated builds via a two stage process.
+  Get a control image, then launch a system image with it.
+
+  1) Obtain a control image.
+
+     The scripts in sources/native-build (such as hello-world.sh and
+     static-tools.sh) create build control filesystem images.  For example,
+
+       sources/native-build/hello-world.sh hello-world.hdc
+
+     These are squashfs formatted filesystem images that contain extracted
+     source code, plus a shell script to build that code and upload it to
+     the host (via ftp).
+
+     You're encouraged to create your own control images using the existing
+     native-build scripts as a model.  The images the existing scripts create
+     are available in the downloads/binaries directory.
+
+  2) Use native-build.sh to launch that control image under the emulator.
+
+     This is another wrapper script, this time around dev-environment.sh
+     (which is in turn a wrapper script around run-emulator.sh).
+
+     This wrapper does two things:
+
+     1) Launch an ftp daemon, and inform the virtual system where to find it
+        via the FTP_HOST and FTP_PORT environment variables.  This lets the
+        emulated target system upload files to the host via "ftpput".
+
+        Launching an FTP daemon requires busybox in the $PATH on the host, and
+        uses the busybox nc and ftpd applets to provide an ftp server.  (We
+        can't use an arbitrary one on the host because different ftp daemons
+        understand different command line options.)
+
+        You can set the environment variables $FTP_HOST and $FTP_PORT to point
+        it at an existing FTP daemon.  If either variable is set, the script
+        won't launch a new FTP daemon.  (Note that the default value for
+        $FTP_HOST is 10.0.2.2, which is QEMU's tunnel through to the host
+        system's 127.0.0.1.)
+
+     2) Launch the emulated development environment with a control image, to
+        be mounted on /mnt by the init script.
+
+        Basically this adds "-hdc filename" to the QEMU_EXTRA environment
+        variable to supply a third virtual disk to the emulator, then calls
+        ./dev-environment.sh as normal.
+
+        The Aboriginal Linux init script (sbin/init.sh) checks for the
+        existence of /mnt/init, and runs that if it exists instead of
+        providing an interactive shell prompt.  (It waits three seconds for
+        you to press a key if you do want a shell prompt, in which case you
+        can launch /mnt/init yourself when you're done.)
+
+        When /mnt/init exits, the virtual system shuts down and exits the
+        emulator, just like typing "exit" at the interactive shell prompt.
+
+To cross compile stuff on the host:
+
+  If you already do cross compiling, and would like to use this project's cross
+  compiler to build something else, just add its "bin" subdirectory to the
+  $PATH, and use the build tools prefixed with the target name:
+
+    PATH=$(pwd)/build/cross-compiler-mipsel/bin:$PATH
+    mipsel-gcc -static hello.c -o hello
+    qemu-mipsel hello
+
+  If you don't do cross compiling already, this project isn't going to teach
+  you how, and in fact recommends you just don't go there.  We cross compile
+  so you don't have to.