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       ./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 differenct 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/miniconfig-{busybox,uClibc}
 127
 128     Configuration files used for uClibc and busybox in the miniconfig format.
 129
 130   - ./sources/patches/$PACKAGE-*
 131
 132     Patches for individual patches. They are applied within setup $PACKAGE.
 133
 134   - ./build.sh
 135
 136     Builds all or individual packages based on the files described in
 137     the next section.
 138
 139   - ./sources/sections/$PACKAGE.sh
 140
 141     Every package has a shell script with it's build instructions these
 142     files are sourced from ./build.sh.
 143
 144     They normally start with setupfor $PACKAGE. This extracts the
 145     source tarball to ./build/packages/$PACKAGE and applies all patches
 146     from ./sources/patches/$PACKAGE-*. The patched source is then copied
 147     over to ./build/temp-armv4tl/$PACKAGE where it is built.
 148
 149     The packages are then configured with something like:
 150
 151      PKG_CONFIG_PATH="${STAGING_DIR}/usr/lib/pkgconfig"
 152      LDFLAGS="-L$STAGING_DIR/usr/lib" CFLAGS="-I$STAGING_DIR/usr/include"
 153      ./configure --prefix=/usr
 154
 155     This makes sure that the configure script and the compiler actually
 156     find the already cross compiled libraries and include files.
 157
 158     Packages are then installed into $STAGING_DIR.
 159
 160      make DESTDIR="$STAGING_DIR" install.
 161
 162     The parts which are actually needed are then copied over to $ROOT_DIR.
 163
 164     If the package is a library some paths which point to the host
 165     systems /usr/lib (because of the --prefix=/usr step) need to be
 166     changed. Without this it wouldn't be possible to link against the
 167     library because the linker would always be redirected to the
 168     hosts /usr/lib directory.
 169
 170     This is the case for libtool's *.la files in $STAGING_DIR/usr/lib
 171     and the pkg-config *.pc files in $STAGING_DIR/usr/lib/pkgconfig.
 172     The paths are changed by the two functions libtool_fixup_libdir
 173     and pkgconfig_fixup_prefix functions.
 174
 175     Finally the build directory is removed with
 176
 177      cleanup $PACKAGE
 178
 179   - ./initramfs.sh
 180
 181     This script copies the content of the $ROOT_OVERLAY directory which
 182     contains all the things which aren't generated by package build scripts
 183     over $ROOT_DIR. It then strips all unnecessary symbols from the binaries
 184     and generates a text file which can be specied as CONFIG_INITRAMFS_SOURCE
 185     during the kernel build. The kernel build system will then based on this
 186     file generate a gziped cpio archive and embed it into the kernel binary.
 187
 188   - ./package.sh
 189
 190     This script simply creates a tarball with the content of the rootfs
 191     directory. You can copy this to your Freerunner and chroot into it to
 192     test things out.