README

   1 Qi Bootmenu System
   2 ==================
   3
   4  This is a set of simple shell scripts to cross compile everything
   5  that is needed in order to run an evas based bootmenu application
   6  with the framebuffer backend.
   7
   8  The ultimate goal is to build a complete initramfs (containing
   9  the bootmenu application) and kernel which can be flashed to your
  10  device.
  11
  12 Quick Start
  13 ===========
  14
  15  In theory all you need to do is run ./build.sh which should
  16  create an uImage-GTA02.bin ready to flash to your device.
  17
  18  Make sure to have the pre-requirements installed.
  19
  20 Pre-Requirements
  21 ================
  22
  23  Host tools
  24  ----------
  25
  26  The build scripts are currently not self contained they require
  27  various host tools. Please make sure you have the following ones
  28  installed:
  29
  30   git svn cvs lzop dfu-util autoconf automake libtool gettext
  31   mkimage pkg-config (>= 0.23)
  32
  33  uClibc armv4tl cross toolchain
  34  ------------------------------
  35
  36  The boot system is uclibc based we can therefore _not_ use the
  37  openmoko toolchain. Instead we need an uclibc based armv4tl
  38  cross toolchain. Building one from scratch is however out of
  39  scope of this project.
  40
  41  By default the scripts download a pre built toolchain from the
  42  Aboriginal Linux project.
  43
  44   http://www.landley.net/code/aboriginal/
  45
  46  It is relocatable and uses a gcc wrapper script to make the gcc path
  47  logic somewhat sane (if that's possible at all). It is the only tested
  48  and supported toolchain.
  49
  50  If for whatever reason you don't want to run a pre built toolchain
  51  you can run ./build.sh aboriginal which compiles one from scratch.
  52  Altneratively you can also build one according to the Aboriginal Linux
  53  documentation, make sure to add the toolchains bin directory to your
  54  $PATH.
  55
  56 Building the boot system
  57 ========================
  58
  59  Configuring the build
  60  ---------------------
  61
  62  There are a few configuration settings which can be used to tweek the
  63  build system in various ways. They can be specified on the command line
  64  or via the top level config file which is sourced by the other scripts.
  65
  66  What follows is a short descritption of the most important ones:
  67
  68   $MACHINE has to be set to either GTA01 or GTA02 the latter is assumed
  69            the variable isn't specified
  70
  71   $STATIC  build qi-bootmenu statically and don't install shared
  72            libraries. This results in a slightly smaller + faster
  73            initramfs. This is enabled by default.
  74
  75  Building the initramfs content, kernel and bootloader
  76  -----------------------------------------------------
  77
  78  Building the whole system (all packages) including kernel and bootloader
  79  is as simple as executing the ./build.sh shell script. This will build
  80  a kernel (uImage-$MACHINE.bin) containing the whole boot system as an
  81  initramfs and a slightly modified version of the bootloader Qi (qi-*.udfu).
  82
  83  If you just want to rebuild an individual package then pass it's name as
  84  argument. For example if you just want to rebuild qi-bootmenu then run.
  85
  86   ./build.sh qi-bootmenu
  87
  88 Installing/Flashing the boot system
  89 ===================================
  90
  91  The last step should have built a kernel (uImage-$MACHINE.bin) and a
  92  bootloader (qi-*.udfu) these files can be flashed in the normal way as
  93  described in:
  94
  95   http://wiki.openmoko.org/wiki/Flashing
  96
  97  There are also two scripts included which should make this a straight
  98  forward process. Just run the following command and your newly built
  99  boot system should be installed.
 100
 101   ./flash-kernel.sh && ./flash-qi.sh
 102
 103 How it all works
 104 ================
 105
 106  The basic idea is to first install everything into a $STAGING_DIR and then
 107  selectively copy the required bits over to $ROOT_DIR. In the end the
 108  $ROOT_OVERLAY directory, which contains configuration files and other things
 109  which aren't generated by package builds, is copied over $ROOT_DIR.
 110
 111  After the packages are installed into $STAGING_DIR some paths which point
 112  to the host systems /usr/lib (because of the --prefix=/usr step) need to
 113  be changed. Without this the linker would search for the libraries in the
 114  hosts systems library directory.
 115
 116  Below are some descriptions of various parts of the build system.
 117  A big part of the code was actually taken from the FWL scripts that's why
 118  both system work in similar ways.
 119
 120   - ./sources/include.sh
 121
 122     Contains various environment variables which are needed in other scripts.
 123
 124   - ./sources/functions-fwl.sh and ./sources/functions.sh
 125
 126     Home of all shell functions which are used in the other parts of the
 127     system. These files are sourced from include.sh. functions-fwl.sh is
 128     mostly taken from the FWL project.
 129
 130   - ./download.sh
 131
 132     Downloads all the required source packages either with wget from
 133     some http/ftp server or uses a source code management system to
 134     check it out from a repository.
 135
 136   - ./sources/configs/miniconfig-{busybox,uClibc,linux}
 137
 138     Configuration files used for busybox, uClibc and the linux kernel
 139     in the miniconfig format.
 140
 141   - ./sources/patches/$PACKAGE-*
 142
 143     Patches for individual packages. They are applied within setup $PACKAGE.
 144
 145   - ./build.sh
 146
 147     Builds all or individual packages based on the files described in
 148     the next section.
 149
 150   - ./sources/sections/$PACKAGE.sh
 151
 152     Every package has a shell script with it's build instructions these
 153     files are sourced from ./build.sh.
 154
 155     They normally start with setupfor $PACKAGE. This extracts the
 156     source tarball to ./build/packages/$PACKAGE and applies all patches
 157     from ./sources/patches/$PACKAGE-*. The patched source is then copied
 158     over to ./build/temp-armv4tl/$PACKAGE where it is built.
 159
 160     The packages are then configured with something like:
 161
 162      PKG_CONFIG_PATH="${STAGING_DIR}/usr/lib/pkgconfig"
 163      CCWRAP_TOPDIR="$STAGING_DIR/usr"
 164      CFLAGS="-I$STAGING_DIR/usr/include"
 165      ./configure --prefix=/usr
 166
 167     This makes sure that the configure script and the compiler actually
 168     find the already cross compiled libraries and include files.
 169
 170     Packages are then installed into $STAGING_DIR.
 171
 172      make DESTDIR="$STAGING_DIR" install.
 173
 174     The parts which are actually needed are then copied over to $ROOT_DIR.
 175
 176     If the package is a library some paths which point to the host
 177     systems /usr/lib (because of the --prefix=/usr step) need to be
 178     changed. Without this it wouldn't be possible to link against the
 179     library because the linker would always be redirected to the
 180     hosts /usr/lib directory.
 181
 182     This is the case for libtool's *.la files in $STAGING_DIR/usr/lib
 183     and the pkg-config *.pc files in $STAGING_DIR/usr/lib/pkgconfig.
 184     The paths are changed by the two functions libtool_fixup_libdir
 185     and pkgconfig_fixup_prefix which are located in sources/functions.sh.
 186
 187     Finally the build directory is removed with
 188
 189      cleanup $PACKAGE
 190
 191   - ./initramfs.sh
 192
 193     This script copies the content of the $ROOT_OVERLAY directory which
 194     contains all the things which aren't generated by package build scripts
 195     over $ROOT_DIR. It then strips all unnecessary symbols from the binaries
 196     and generates a text file which can be specied as CONFIG_INITRAMFS_SOURCE
 197     during the kernel build. The kernel build system will then based on this
 198     file generate a gziped cpio archive and embed it into the kernel binary.
 199
 200   - ./package.sh
 201
 202     This script simply creates a tarball with the content of the rootfs
 203     directory. You can copy this to your Freerunner and chroot into it to
 204     test things out.
 205
 206 Changes to vanilla Qi
 207 =====================
 208
 209  The boot system also works with the unmodified version of Qi as found in
 210  the openmoko git repository.
 211
 212   http://git.openmoko.org/?p=qi.git
 213
 214  The patches which are applied are thus not strictly necessary but they have
 215  a few advantages over vanilla Qi.
 216
 217   - You won't have to mark your SD-card partition as not bootable via
 218     noboot-$MACHINE files
 219
 220   - It's slightly faster because after the first AUX press no further
 221     SD-card partitions are scanned Qi proceeds straight away with
 222     booting from NAND
 223
 224   - The NAND partition is ignored by the bootmenu because Qi will pass
 225     the required parameters on the kernel command line this reduces
 226     boot time because mounting an jffs2 file system is slow.