Remove unreferenced shared libraries prior to initramfs generation
[qi-bootmenu-system/guyou.git] / README
blobefdae5e75a7b1e8e21ddeb8bbbbc71c13d90e51b
1 Qi Bootmenu System
2 ==================
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.
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.
12 Pre-Requirements
13 ================
15  uClibc armv4tl cross toolchain
16  ------------------------------
18  The boot system is uclibc based you can therefore _not_ use the 
19  openmoko toolchain. Instead you need to build your own cross
20  compiler. This is however out of scope of this project.
22  I strongly recommend you to use a toolchain from the FWL project
24   http://www.landley.net/code/firmware/
26  It is relocatable and uses a gcc wrapper script to make the gcc path 
27  logic somewhat sane (if that's possible at all). It is currently 
28  the only tested and supported toolchain.
30  You can now either download a pre built uclibc toolchain from:
32   http://impactlinux.com/fwl/downloads/binaries/cross-compiler-armv4tl.tar.bz2
34  or build one from scratch with the following instructions:
36   1. Download and extract
38       http://impactlinux.com/fwl/downloads/firmware-0.9.10.tar.bz2
40   2. Build the cross compiler
42       ./download.sh && ./simple-cross-compiler.sh armv4tl
44   3. Copy the build/simple-cross-compiler-armv4tl directory to a
45      place of your choice.
47  Now that you have a cross toolchain add it's bin directory to
48  your $PATH.
50   cd simple-cross-compiler-armv4tl/bin && export PATH=`pwd`:$PATH
52  Host tools
53  ----------
55  The build scripts are currently not self contained they require
56  various host tools. Please make sure you have the following ones
57  installed:
59   git svn cvs lzop dfu-util autoconf automake libtool gettext
60   mkimage
62 Building the boot system
63 ========================
65  Environment setup
66  -----------------
68  Make sure you have your cross toolchain somewhere in your $PATH,
69  if this is not the case then add it.
71   cd cross-compiler-armv4tl/bin && export PATH=`pwd`:$PATH
73  By default the scripts assume 'armv4tl-' as toolchain prefix if your 
74  toolchain uses something different then set the $CROSS environment 
75  variable accordingly.
77  Configuring the build
78  ---------------------
80  There are a few configuration settings which can be used to tweek the
81  build system in various ways. They can be specified on the command line
82  or via the top level config file which is sourced by the other scripts.
84  What follows is a short descritption of the most important ones:
86   $MACHINE has to be set to either GTA01 or GTA02 the latter is assumed
87            the variable isn't specified
89   $STATIC  build qi-bootmenu statically and don't install shared 
90            libraries. This results in a slightly smaller + faster
91            initramfs. 
93  Building the initramfs content, kernel and bootloader
94  -----------------------------------------------------
96  Building the whole system (all packages) including kernel and bootloader
97  is as simple as executing the ./build.sh shell script. This will build
98  a kernel (uImage-$MACHINE.bin) containing the whole boot system as an
99  initramfs and a slightly modified version of the bootloader Qi (qi-*.udfu).
101  If you just want to rebuild an individual package then pass it's name as 
102  argument. For example if you just want to rebuild qi-bootmenu then run.
104   ./build.sh qi-bootmenu
106 Installing/Flashing the boot system
107 ===================================
109  The last step should have built a kernel (uImage-$MACHINE.bin) and a
110  bootloader (qi-*.udfu) these files can be flashed in the normal way as
111  described in:
113   http://wiki.openmoko.org/wiki/Flashing
115  There are also two scripts included which should make this a straight
116  forward process. Just run the following command and your newly built
117  boot system should be installed.
119   ./flash-kernel.sh && ./flash-qi.sh
121 How it all works
122 ================
124  The basic idea is to first install everything into a $STAGING_DIR and then
125  selectively copy the required bits over to $ROOT_DIR. In the end the
126  $ROOT_OVERLAY directory, which contains configuration files and other things
127  which aren't generated by package builds, is copied over $ROOT_DIR. 
129  After the packages are installed into $STAGING_DIR some paths which point
130  to the host systems /usr/lib (because of the --prefix=/usr step) need to
131  be changed. Without this the linker would search for the libraries in the
132  hosts systems library directory. 
134  Below are some descriptions of various parts of the build system. 
135  A big part of the code was actually taken from the FWL scripts that's why
136  both system work in similar ways.
138   - ./sources/include.sh
140     Contains various environment variables which are needed in other scripts.
142   - ./sources/functions-fwl.sh and ./sources/functions.sh
144     Home of all shell functions which are used in the other parts of the
145     system. These files are sourced from include.sh. functions-fwl.sh is
146     mostly taken from the FWL project.
148   - ./download.sh 
150     Downloads all the required source packages either with wget from
151     some http/ftp server or uses a source code management system to 
152     check it out from a repository.
154   - ./sources/configs/miniconfig-{busybox,uClibc,linux}
156     Configuration files used for busybox, uClibc and the linux kernel 
157     in the miniconfig format.
159   - ./sources/patches/$PACKAGE-*
161     Patches for individual packages. They are applied within setup $PACKAGE.
163   - ./build.sh
165     Builds all or individual packages based on the files described in
166     the next section.
168   - ./sources/sections/$PACKAGE.sh
170     Every package has a shell script with it's build instructions these
171     files are sourced from ./build.sh.
173     They normally start with setupfor $PACKAGE. This extracts the
174     source tarball to ./build/packages/$PACKAGE and applies all patches 
175     from ./sources/patches/$PACKAGE-*. The patched source is then copied
176     over to ./build/temp-armv4tl/$PACKAGE where it is built.
178     The packages are then configured with something like:
180      PKG_CONFIG_PATH="${STAGING_DIR}/usr/lib/pkgconfig"
181      CCWRAP_TOPDIR="$STAGING_DIR/usr"
182      CFLAGS="-I$STAGING_DIR/usr/include" 
183      ./configure --prefix=/usr 
185     This makes sure that the configure script and the compiler actually 
186     find the already cross compiled libraries and include files. 
188     Packages are then installed into $STAGING_DIR.
190      make DESTDIR="$STAGING_DIR" install.
192     The parts which are actually needed are then copied over to $ROOT_DIR.
194     If the package is a library some paths which point to the host 
195     systems /usr/lib (because of the --prefix=/usr step) need to be 
196     changed. Without this it wouldn't be possible to link against the
197     library because the linker would always be redirected to the
198     hosts /usr/lib directory.
200     This is the case for libtool's *.la files in $STAGING_DIR/usr/lib 
201     and the pkg-config *.pc files in $STAGING_DIR/usr/lib/pkgconfig. 
202     The paths are changed by the two functions libtool_fixup_libdir
203     and pkgconfig_fixup_prefix which are located in sources/functions.sh.
205     Finally the build directory is removed with
207      cleanup $PACKAGE
209   - ./initramfs.sh
211     This script copies the content of the $ROOT_OVERLAY directory which
212     contains all the things which aren't generated by package build scripts
213     over $ROOT_DIR. It then strips all unnecessary symbols from the binaries 
214     and generates a text file which can be specied as CONFIG_INITRAMFS_SOURCE 
215     during the kernel build. The kernel build system will then based on this
216     file generate a gziped cpio archive and embed it into the kernel binary.
218   - ./package.sh
220     This script simply creates a tarball with the content of the rootfs 
221     directory. You can copy this to your Freerunner and chroot into it to
222     test things out.
224 Changes to vanilla Qi
225 =====================
227  The boot system also works with the unmodified version of Qi as found in
228  the openmoko git repository.
230   http://git.openmoko.org/?p=qi.git
232  The patches which are applied are thus not strictly necessary but they have 
233  a few advantages over vanilla Qi.
235   - You won't have to mark your SD-card partition as not bootable via
236     noboot-$MACHINE files
238   - It's slightly faster because after the first AUX press no further
239     SD-card partitions are scanned Qi proceeds straight away with
240     booting from NAND
242   - The NAND partition is ignored by the bootmenu because Qi will pass
243     the required parameters on the kernel command line this reduces
244     boot time because mounting an jffs2 file system is slow.