view www/downloads/README @ 1315:7d086d8fa348

Update some READMEs.
author Rob Landley <rob@landley.net>
date Fri, 03 Dec 2010 21:20:28 -0600
parents 3a4fccf92f58
children
line wrap: on
line source

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
rest of this README describes the contents of the current source tarball.

Scripts that build code for a specific target (everything except download.sh,
clean.sh, and host-tools.sh) produce output under the "build" directory, in a
subdirectory with the same name as the script plus the name of the target
architecture the output is built for.  At the end of each stage, the
result is saved to a tarball of the same name.

All downloaded files wind up in the "packages" directory.  Output from
compiles is generated in the "build" directory.  These are the only two
directories the build writes to, and both directories may be deleted and
then recreated by the build scripts.

To do a full "distclean", do "rm -rf build packages" from the top level
directory.

None of these scripts need to be run as root -- a design goal of
Aboriginal Linux is that root access on the host is never required.

These scripts include the following stages:

  build.sh ARCH

    Top level wrapper script which builds a system image for a target,
    by calling most of the other scripts listed here in the appropriate
    order.  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 the build's behavior,
    see the file "configure" for details.

  download.sh

    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.

    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.

  host-tools.sh

    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.

    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
    used by later stages if it exists.  It is not target specific, and only
    needs to be run once when building multiple architectures.

  simple-cross-compiler.sh ARCH

    Creates a cross compiler for the selected target architecture, built from
    gcc, binutils, uClibc, and the Linux kernel headers.  This compiler runs
    on the host and produces programs that run on the target.

    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.  It
    doesn't include thread support, uClibc++, or the shared version of libgcc.

  cross-compiler.sh ARCH

    This optional step creates a more full-featured cross compiler, with
    thread support, uClibc++, and the shared version of libgcc.  (This is
    not required to build a system image, but the prebuilt binary compilers
    shipped in the downloads/binaries directory are built this way.)

    The build.sh wrapper script only calls this stage if CROSS_HOST_ARCH is
    set, indicating which host architecture to build for.  (For PC hardware,
    i686 is a good value, since most 64 bit PCs can run 32 bit code.)

    This compiler is statically linked against uClibc, for maximum
    portability.  (You can set BUILD_STATIC=none to dynamically link instead,
    but then have to install uClibc's shared libraries on the host.)

  native-compiler.sh ARCH

    This step creates a compiler for the selected target, using one
    or more of the existing simple cross compilers.  The compiler it produces
    runs on the target and produces programs that also run on the target.

    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 compiler includes binutils, gcc, make, bash, and distcc.  Because
    it's a native compiler, the executable names do not have any prefixes the
    way the cross compilers do.  (I.E. just "ld" instead of "$ARCH-ld".)

  simple-root-filesystem.sh ARCH

    Creates a root filesystem (with uCLibc, BusyBox, and an init script)
    that contains just enough infrastructure to boot up to a shell prompt.

  root-filesystem.sh ARCH

    Combines the simple root filesystem and native compiler into a single
    root filesystem, producing a bootable root filesystem with development
    tools.

  system-image.sh ARCH

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

  run-from-build.sh ARCH

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

    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.

The sources/more directory contains additional scripts the user can run,
but which are not called from build.sh.  This directory contains the external
user interfaces the user can call directly which are not build stages.
See more/README in the Aboriginal source code for details.