Integrate pre built Aboriginal Linux uclibc cross toolchain

[qi-bootmenu-system.git] / README

Qi Bootmenu System
==================

 This is a set of simple shell scripts to cross compile everything
 that is needed in order to run an evas based bootmenu application 
 with the framebuffer backend.

 The ultimate goal is to build a complete initramfs (containing
 the bootmenu application) and kernel which can be flashed to your
 device.

Quick Start
===========

 In theory all you need to do is run ./build.sh which should
 create an uImage-GTA02.bin ready to flash to your device. 

 Make sure to have the pre-requirements installed.

Pre-Requirements
================

 Host tools
 ----------

 The build scripts are currently not self contained they require
 various host tools. Please make sure you have the following ones
 installed:

  git svn cvs lzop dfu-util autoconf automake libtool gettext
  mkimage pkg-config (>= 0.23)

 uClibc armv4tl cross toolchain
 ------------------------------

 The boot system is uclibc based we can therefore _not_ use the 
 openmoko toolchain. Instead we need an uclibc based armv4tl
 cross toolchain. Building one from scratch is however out of 
 scope of this project.

 By default the scripts download a pre built toolchain from the
 Aboriginal Linux project.
 
  http://www.landley.net/code/aboriginal/

 It is relocatable and uses a gcc wrapper script to make the gcc path 
 logic somewhat sane (if that's possible at all). It is the only tested
 and supported toolchain.

 If for whatever reason you don't want to run a pre built toolchain
 you can run ./build.sh aboriginal which compiles one from scratch. 
 Altneratively you can also build one according to the Aboriginal Linux
 documentation, make sure to add the toolchains bin directory to your
 $PATH. 

Building the boot system
========================

 Configuring the build
 ---------------------

 There are a few configuration settings which can be used to tweek the
 build system in various ways. They can be specified on the command line
 or via the top level config file which is sourced by the other scripts.

 What follows is a short descritption of the most important ones:

  $MACHINE has to be set to either GTA01 or GTA02 the latter is assumed
           the variable isn't specified

  $STATIC  build qi-bootmenu statically and don't install shared 
           libraries. This results in a slightly smaller + faster
           initramfs. This is enabled by default. 
 
 Building the initramfs content, kernel and bootloader
 -----------------------------------------------------

 Building the whole system (all packages) including kernel and bootloader
 is as simple as executing the ./build.sh shell script. This will build
 a kernel (uImage-$MACHINE.bin) containing the whole boot system as an
 initramfs and a slightly modified version of the bootloader Qi (qi-*.udfu).

 If you just want to rebuild an individual package then pass it's name as 
 argument. For example if you just want to rebuild qi-bootmenu then run.

  ./build.sh qi-bootmenu

Installing/Flashing the boot system
===================================

 The last step should have built a kernel (uImage-$MACHINE.bin) and a
 bootloader (qi-*.udfu) these files can be flashed in the normal way as
 described in:

  http://wiki.openmoko.org/wiki/Flashing

 There are also two scripts included which should make this a straight
 forward process. Just run the following command and your newly built
 boot system should be installed.

  ./flash-kernel.sh && ./flash-qi.sh

How it all works
================

 The basic idea is to first install everything into a $STAGING_DIR and then
 selectively copy the required bits over to $ROOT_DIR. In the end the
 $ROOT_OVERLAY directory, which contains configuration files and other things
 which aren't generated by package builds, is copied over $ROOT_DIR. 
 
 After the packages are installed into $STAGING_DIR some paths which point
 to the host systems /usr/lib (because of the --prefix=/usr step) need to
 be changed. Without this the linker would search for the libraries in the
 hosts systems library directory. 
 
 Below are some descriptions of various parts of the build system. 
 A big part of the code was actually taken from the FWL scripts that's why
 both system work in similar ways.

  - ./sources/include.sh

    Contains various environment variables which are needed in other scripts.

  - ./sources/functions-fwl.sh and ./sources/functions.sh

    Home of all shell functions which are used in the other parts of the
    system. These files are sourced from include.sh. functions-fwl.sh is
    mostly taken from the FWL project.

  - ./download.sh 
 
    Downloads all the required source packages either with wget from
    some http/ftp server or uses a source code management system to 
    check it out from a repository.

  - ./sources/configs/miniconfig-{busybox,uClibc,linux}

    Configuration files used for busybox, uClibc and the linux kernel 
    in the miniconfig format.

  - ./sources/patches/$PACKAGE-*

    Patches for individual packages. They are applied within setup $PACKAGE.
 
  - ./build.sh

    Builds all or individual packages based on the files described in
    the next section.

  - ./sources/sections/$PACKAGE.sh

    Every package has a shell script with it's build instructions these
    files are sourced from ./build.sh.

    They normally start with setupfor $PACKAGE. This extracts the
    source tarball to ./build/packages/$PACKAGE and applies all patches 
    from ./sources/patches/$PACKAGE-*. The patched source is then copied
    over to ./build/temp-armv4tl/$PACKAGE where it is built.

    The packages are then configured with something like:

     PKG_CONFIG_PATH="${STAGING_DIR}/usr/lib/pkgconfig"
     CCWRAP_TOPDIR="$STAGING_DIR/usr"
     CFLAGS="-I$STAGING_DIR/usr/include" 
     ./configure --prefix=/usr 

    This makes sure that the configure script and the compiler actually 
    find the already cross compiled libraries and include files. 

    Packages are then installed into $STAGING_DIR.

     make DESTDIR="$STAGING_DIR" install.

    The parts which are actually needed are then copied over to $ROOT_DIR.

    If the package is a library some paths which point to the host 
    systems /usr/lib (because of the --prefix=/usr step) need to be 
    changed. Without this it wouldn't be possible to link against the
    library because the linker would always be redirected to the
    hosts /usr/lib directory.

    This is the case for libtool's *.la files in $STAGING_DIR/usr/lib 
    and the pkg-config *.pc files in $STAGING_DIR/usr/lib/pkgconfig. 
    The paths are changed by the two functions libtool_fixup_libdir
    and pkgconfig_fixup_prefix which are located in sources/functions.sh.

    Finally the build directory is removed with
 
     cleanup $PACKAGE

  - ./initramfs.sh

    This script copies the content of the $ROOT_OVERLAY directory which
    contains all the things which aren't generated by package build scripts
    over $ROOT_DIR. It then strips all unnecessary symbols from the binaries 
    and generates a text file which can be specied as CONFIG_INITRAMFS_SOURCE 
    during the kernel build. The kernel build system will then based on this
    file generate a gziped cpio archive and embed it into the kernel binary.

  - ./package.sh

    This script simply creates a tarball with the content of the rootfs 
    directory. You can copy this to your Freerunner and chroot into it to
    test things out.

Changes to vanilla Qi
=====================

 The boot system also works with the unmodified version of Qi as found in
 the openmoko git repository.

  http://git.openmoko.org/?p=qi.git

 The patches which are applied are thus not strictly necessary but they have 
 a few advantages over vanilla Qi.

  - You won't have to mark your SD-card partition as not bootable via
    noboot-$MACHINE files

  - It's slightly faster because after the first AUX press no further
    SD-card partitions are scanned Qi proceeds straight away with
    booting from NAND

  - The NAND partition is ignored by the bootmenu because Qi will pass
    the required parameters on the kernel command line this reduces
    boot time because mounting an jffs2 file system is slow.