Rename download_scm to download_svn and just care about svn

[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 elementary based applications
 with the framebuffer backend. The ultimate goal is to create a
 file with all the contents of the initramfs which then can be 
 specified during kernel compilation. 

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

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

 The boot system is uclibc based you can therefore _not_ use the 
 openmoko toolchain. Instead you need to build your own cross
 compiler. This is however out of scoup of this project.

 I strongly recommend you to use a somewhat modified toolchain from 
 the FWL project (http://www.landley.net/code/firmware/). 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 currently 
 the only tested and supported toolchain.

 You can now either download a pre built uclibc toolchain from:

  http://www.brain-dump.org/tmp/qi-bootmenu-system/firmware-0.9.7-cross-compiler-armv4tl.tar.bz2

 or build one from scratch with the following instructions:

  1. Download and extract

      http://landley.net/code/firmware/downloads/firmware-0.9.7.tar.bz2

  2. Download and extract into the same directory so that the files are
     added to the existing directory structure.

      http://www.brain-dump.org/tmp/qi-bootmenu-system/firmware-0.9.7-armv4tl-patch.tar.bz2

  3. Build the cross compiler

      ./cross-compiler.sh armv4tl

  4. Go into the build/cross-compiler-armv4tl/bin directory and
     create symlinks to every binary with the following prefix:

      armv4tl-unknown-linux-gnueabi-

     The following script does this when run from within the 
     build/cross-compiler-armv4tl/bin directory:

      #!/bin/sh

      OLD_PREFIX=armv4tl
      NEW_PREFIX=armv4tl-unknown-linux-gnueabi

      for OLD_APP in $OLD_PREFIX-*; do 
        APP=$(echo $OLD_APP | sed 's/.*-\(.*\)$/\1/')
        ln -sf "$OLD_APP" "$NEW_PREFIX-$APP" 
      done

  5. Copy the build/cross-compiler-armv4tl directory to a
     place of your choice.

 Now that you have a cross toolchain add it's bin directory to
 your $PATH.

  cd cross-compiler-armv4tl/bin && export PATH=`pwd`:$PATH

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

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

  edje_cc git svn patch autoconf automake libtool gettext cvs 
  wget xargs sha1sum sed find

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

 Environment setup
 -----------------

 Make sure you have your cross toolchain somewhere in your $PATH,
 if this is not the case then add it.

  cd cross-compiler-armv4tl/bin && export PATH=`pwd`:$PATH
 
 Building
 --------

 Building the whole system (all packages) is as simple as executing
 the ./build.sh shell script. If you just want to build an individual
 package then pass it as argument. For example if you just want to 
 rebuild elementary then run.

  ./build.sh elementary

 Generating initramfs
 --------------------

 Now run ./initramfs.sh this should generate a text file (initramfs-files
 in the top level driectory) with all the content of the rootfs direcory. 
 This text file can then be specied as CONFIG_INITRAMFS_SOURCE during the 
 kernel build. 

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/miniconfig-{busybox,uClibc}

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

  - ./sources/patches/$PACKAGE-*

    Patches for individual patches. 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/sources/$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" 
     LDFLAGS="-L$STAGING_DIR/usr/lib" 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 functions.

    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.