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