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