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
15 In theory all you need to do is run ./build.sh which should
16 create an uImage-GTA02.bin ready to flash to your device.
18 ./build.sh && ./flash-kernel.sh && ./flash-qi.sh
20 Building the boot system
21 ========================
26 There are a few configuration settings which can be used to tweek the
27 build system in various ways. They can be specified on the command line
28 or via the top level config file which is sourced by the other scripts.
30 What follows is a short descritption of the most important ones:
32 $MACHINE has to be set to either GTA01 or GTA02 the latter is assumed
33 the variable isn't specified
35 $STATIC build qi-bootmenu statically and don't install shared
36 libraries. This results in a slightly smaller + faster
37 initramfs. This is enabled by default.
39 Building the initramfs content, kernel and bootloader
40 -----------------------------------------------------
42 Building the whole system (all packages) including kernel and bootloader
43 is as simple as executing the ./build.sh shell script. This will build
44 a kernel (uImage-$MACHINE.bin) containing the whole boot system as an
45 initramfs and a slightly modified version of the bootloader Qi (qi-*.udfu).
47 If you just want to rebuild an individual package then pass it's name as
48 argument. For example if you just want to rebuild qi-bootmenu then run.
50 ./build.sh qi-bootmenu
52 Installing/Flashing the boot system
53 ===================================
55 The last step should have built a kernel (uImage-$MACHINE.bin) and a
56 bootloader (qi-*.udfu) these files can be flashed in the normal way as
59 http://wiki.openmoko.org/wiki/Flashing
61 There are also two scripts included which should make this a straight
62 forward process. Just run the following command and your newly built
63 boot system should be installed.
65 ./flash-kernel.sh && ./flash-qi.sh
70 uClibc armv4tl cross toolchain
71 ------------------------------
73 The boot system is uclibc based we can therefore _not_ use the
74 openmoko toolchain. Instead we need an uclibc based armv4tl
75 cross toolchain. Building one from scratch is however out of
76 scope of this project.
78 By default the scripts download a pre built toolchain from the
79 Aboriginal Linux project.
81 http://www.landley.net/code/aboriginal/
83 It is relocatable and uses a gcc wrapper script to make the gcc path
84 logic somewhat sane (if that's possible at all). It is the only tested
85 and supported toolchain.
87 If for whatever reason you don't want to run a pre built toolchain
88 you can run ./build.sh aboriginal which compiles one from scratch.
89 Altneratively you can also build one according to the Aboriginal Linux
90 documentation, make sure to add the toolchains bin directory to your
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.
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.
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.
110 - ./sources/include.sh
112 Contains various environment variables which are needed in other scripts.
114 - ./sources/functions-fwl.sh and ./sources/functions.sh
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.
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.
126 - ./sources/configs/miniconfig-{busybox,uClibc,linux}
128 Configuration files used for busybox, uClibc and the linux kernel
129 in the miniconfig format.
131 - ./sources/patches/$PACKAGE-*
133 Patches for individual packages. They are applied within setup $PACKAGE.
137 Builds all or individual packages based on the files described in
140 - ./sources/sections/$PACKAGE.sh
142 Every package has a shell script with it's build instructions these
143 files are sourced from ./build.sh.
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.
150 The packages are then configured with something like:
152 PKG_CONFIG_PATH="${STAGING_DIR}/usr/lib/pkgconfig"
153 CCWRAP_TOPDIR="$STAGING_DIR/usr"
154 CFLAGS="-I$STAGING_DIR/usr/include"
155 ./configure --prefix=/usr
157 This makes sure that the configure script and the compiler actually
158 find the already cross compiled libraries and include files.
160 Packages are then installed into $STAGING_DIR.
162 make DESTDIR="$STAGING_DIR" install.
164 The parts which are actually needed are then copied over to $ROOT_DIR.
166 If the package is a library some paths which point to the host
167 systems /usr/lib (because of the --prefix=/usr step) need to be
168 changed. Without this it wouldn't be possible to link against the
169 library because the linker would always be redirected to the
170 hosts /usr/lib directory.
172 This is the case for libtool's *.la files in $STAGING_DIR/usr/lib
173 and the pkg-config *.pc files in $STAGING_DIR/usr/lib/pkgconfig.
174 The paths are changed by the two functions libtool_fixup_libdir
175 and pkgconfig_fixup_prefix which are located in sources/functions.sh.
177 Finally the build directory is removed with
183 This script copies the content of the $ROOT_OVERLAY directory which
184 contains all the things which aren't generated by package build scripts
185 over $ROOT_DIR. It then strips all unnecessary symbols from the binaries
186 and generates a text file which can be specied as CONFIG_INITRAMFS_SOURCE
187 during the kernel build. The kernel build system will then based on this
188 file generate a gziped cpio archive and embed it into the kernel binary.
192 This script simply creates a tarball with the content of the rootfs
193 directory. You can copy this to your Freerunner and chroot into it to
196 Changes to vanilla Qi
197 =====================
199 The boot system also works with the unmodified version of Qi as found in
200 the openmoko git repository.
202 http://git.openmoko.org/?p=qi.git
204 The patches which are applied are thus not strictly necessary but they have
205 a few advantages over vanilla Qi.
207 - You won't have to mark your SD-card partition as not bootable via
208 noboot-$MACHINE files
210 - It's slightly faster because after the first AUX press no further
211 SD-card partitions are scanned Qi proceeds straight away with
214 - The NAND partition is ignored by the bootmenu because Qi will pass
215 the required parameters on the kernel command line this reduces
216 boot time because mounting an jffs2 file system is slow.