landley/aboriginal

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.

--- 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
      "./a.out" 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
  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 do I use Aboriginal Linux?

To download prebuilt binaries for each target:

    http://landley.net/aboriginal/downloads/binaries

  The "system-image" tarballs are what you need to boot a virtual target
  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 (using the dev-environment.sh script, explained later in this file).

  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 from source:

  Download the most recent set of build scripts from:

      http://landley.net/hg/aboriginal/archive/tip.tar.bz2

  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.

  To compile a system image (and all prerequisite stages) for a target:

      ./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).

  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

  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.)

  For more information, see the README file in the download directory.

    http://landley.net/aboriginal/README

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.