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 elementary based applications
   6  with the framebuffer backend. The ultimate goal is to create a
   7  file with all the contents of the initramfs which then can be
   8  specified during kernel compilation.
   9
  10 Pre-Requirements
  11 ================
  12
  13  uClibc armv4tl cross toolchain
  14  ------------------------------
  15
  16  The boot system is uclibc based you can therefore _not_ use the
  17  openmoko toolchain. Instead you need to build your own cross
  18  compiler. This is however out of scoup of this project.
  19
  20  I strongly recommend you to use a somewhat modified toolchain from
  21  the FWL project (http://www.landley.net/code/firmware/). It is
  22  relocatable and uses a gcc wrapper script to make the gcc path
  23  logic somewhat sane (if that's possible at all). It is currently
  24  the only tested and supported toolchain.
  25
  26  You can now either download a pre built uclibc toolchain from:
  27
  28   http://www.brain-dump.org/tmp/qi-bootmenu-system/firmware-0.9.7-cross-compiler-armv4tl.tar.bz2
  29
  30  or build one from scratch with the following instructions:
  31
  32   1. Download and extract
  33
  34       http://landley.net/code/firmware/downloads/firmware-0.9.7.tar.bz2
  35
  36   2. Download and extract into the same directory so that the files are
  37      added to the existing directory structure.
  38
  39       http://www.brain-dump.org/tmp/qi-bootmenu-system/firmware-0.9.7-armv4tl-patch.tar.bz2
  40
  41   3. Build the cross compiler
  42
  43       ./cross-compiler.sh armv4tl
  44
  45   4. Go into the build/cross-compiler-armv4tl/bin directory and
  46      create symlinks to every binary with the following prefix:
  47
  48       armv4tl-unknown-linux-gnueabi-
  49
  50      The following script does this when run from within the
  51      build/cross-compiler-armv4tl/bin directory:
  52
  53       #!/bin/sh
  54
  55       OLD_PREFIX=armv4tl
  56       NEW_PREFIX=armv4tl-unknown-linux-gnueabi
  57
  58       for OLD_APP in $OLD_PREFIX-*; do
  59         APP=$(echo $OLD_APP | sed 's/.*-\(.*\)$/\1/')
  60         ln -sf "$OLD_APP" "$NEW_PREFIX-$APP"
  61       done
  62
  63   5. Copy the build/cross-compiler-armv4tl directory to a
  64      place of your choice.
  65
  66  Now that you have a cross toolchain add it's bin directory to
  67  your $PATH.
  68
  69   cd cross-compiler-armv4tl/bin && export PATH=`pwd`:$PATH
  70
  71  Host tools
  72  ----------
  73
  74  The build scripts are currently not self contained they require
  75  various host tools. Please make sure you have the following ones
  76  installed:
  77
  78   edje_cc git svn patch autoconf automake libtool gettext cvs
  79   wget xargs sha1sum sed find
  80
  81 Building the boot system
  82 ========================
  83
  84  Environment setup
  85  -----------------
  86
  87  Make sure you have your cross toolchain somewhere in your $PATH,
  88  if this is not the case then add it.
  89
  90   cd cross-compiler-armv4tl/bin && export PATH=`pwd`:$PATH
  91
  92  Building
  93  --------
  94
  95  Building the whole system (all packages) is as simple as executing
  96  the ./build.sh shell script. If you just want to build an individual
  97  package then pass it as argument. For example if you just want to
  98  rebuild elementary then run.
  99
 100   ./build.sh elementary
 101
 102  Generating initramfs
 103  --------------------
 104
 105  Now run ./initramfs.sh this should generate a text file (initramfs-files
 106  in the top level driectory) with all the content of the rootfs direcory.
 107  This text file can then be specied as CONFIG_INITRAMFS_SOURCE during the
 108  kernel build.
 109
 110 How it all works
 111 ================
 112
 113  The basic idea is to first install everything into a $STAGING_DIR and then
 114  selectively copy the required bits over to $ROOT_DIR. In the end the
 115  $ROOT_OVERLAY directory, which contains configuration files and other things
 116  which aren't generated by package builds, is copied over $ROOT_DIR.
 117
 118  After the packages are installed into $STAGING_DIR some paths which point
 119  to the host systems /usr/lib (because of the --prefix=/usr step) need to
 120  be changed. Without this the linker would search for the libraries in the
 121  hosts systems library directory.
 122
 123  Below are some descriptions of various parts of the build system.
 124  A big part of the code was actually taken from the FWL scripts that's why
 125  both system work in similar ways.
 126
 127   - ./sources/include.sh
 128
 129     Contains various environment variables which are needed in other scripts.
 130
 131   - ./sources/functions-fwl.sh and ./sources/functions.sh
 132
 133     Home of all shell functions which are used in the other parts of the
 134     system. These files are sourced from include.sh. functions-fwl.sh is
 135     mostly taken from the FWL project.
 136
 137   - ./download.sh
 138
 139     Downloads all the required source packages either with wget from
 140     some http/ftp server or uses a source code management system to
 141     check it out from a repository.
 142
 143   - ./sources/miniconfig-{busybox,uClibc}
 144
 145     Configuration files used for uClibc and busybox in the miniconfig format.
 146
 147   - ./sources/patches/$PACKAGE-*
 148
 149     Patches for individual patches. They are applied within setup $PACKAGE.
 150
 151   - ./build.sh
 152
 153     Builds all or individual packages based on the files described in
 154     the next section.
 155
 156   - ./sources/sections/$PACKAGE.sh
 157
 158     Every package has a shell script with it's build instructions these
 159     files are sourced from ./build.sh.
 160
 161     They normally start with setupfor $PACKAGE. This extracts the
 162     source tarball to ./build/sources/$PACKAGE and applies all patches
 163     from ./sources/patches/$PACKAGE-*. The patched source is then copied
 164     over to ./build/temp-armv4tl/$PACKAGE where it is built.
 165
 166     The packages are then configured with something like:
 167
 168      PKG_CONFIG_PATH="${STAGING_DIR}/usr/lib/pkgconfig"
 169      LDFLAGS="-L$STAGING_DIR/usr/lib" CFLAGS="-I$STAGING_DIR/usr/include"
 170      ./configure --prefix=/usr
 171
 172     This makes sure that the configure script and the compiler actually
 173     find the already cross compiled libraries and include files.
 174
 175     Packages are then installed into $STAGING_DIR.
 176
 177      make DESTDIR="$STAGING_DIR" install.
 178
 179     The parts which are actually needed are then copied over to $ROOT_DIR.
 180
 181     If the package is a library some paths which point to the host
 182     systems /usr/lib (because of the --prefix=/usr step) need to be
 183     changed. Without this it wouldn't be possible to link against the
 184     library because the linker would always be redirected to the
 185     hosts /usr/lib directory.
 186
 187     This is the case for libtool's *.la files in $STAGING_DIR/usr/lib
 188     and the pkg-config *.pc files in $STAGING_DIR/usr/lib/pkgconfig.
 189     The paths are changed by the two functions libtool_fixup_libdir
 190     and pkgconfig_fixup_prefix functions.
 191
 192     Finally the build directory is removed with
 193
 194      cleanup $PACKAGE
 195
 196   - ./initramfs.sh
 197
 198     This script copies the content of the $ROOT_OVERLAY directory which
 199     contains all the things which aren't generated by package build scripts
 200     over $ROOT_DIR. It then strips all unnecessary symbols from the binaries
 201     and generates a text file which can be specied as CONFIG_INITRAMFS_SOURCE
 202     during the kernel build. The kernel build system will then based on this
 203     file generate a gziped cpio archive and embed it into the kernel binary.
 204
 205   - ./package.sh
 206
 207     This script simply creates a tarball with the content of the rootfs
 208     directory. You can copy this to your Freerunner and chroot into it to
 209     test things out.