====== Cross compile per OpenMoko ======

Per compilare un'applicazione per il FreeRunner su sistema operativo OpenMoko possiamo scegliere tre strade:

  * **[[http://wiki.openmoko.org/wiki/Qemu|Qemu]]**. È possibile eseguire l'intero sistema opertativo OpenMoko sotto Qemu, tuttavia l'hardware GTA02 (FreeRunner) non è pienamente supportato. Inoltre le utility fornite a corredo dell'emulatore sono scritte per il GTA01 (Neo1973), pertanto la strada per avere l'emulatore funzionante non è semplice. L'emulazione del GTA01/GTA02 non è inclusa nella distrubuzione ufficiale Qemu, bisogna scaricare i sorgenti dal [[https://svn.openmoko.org/trunk/src/host/qemu-neo1973|repository SVN]] apposito.
  * **[[http://wiki.openmoko.org/wiki/MokoMakefile|MokoMakeFile]]**. Si tratta di uno script che provvede a scaricare e configurare un ambiente completo derivato da OpenEmbedded. Il progetto è considerato **obsoleto**.
  * **[[http://wiki.openmoko.org/wiki/Toolchain|Toolchain]]**. Questa è la strada consigliata sia per lo sviluppo di una singola applicazione che per un'intera distrubuzione. Consente di compilare **codice arm** su piattaforma i686 o amd64.

===== Installare la toolchain =====

Per installare la toolchain su Debian Lenny si sono seguite queste istruzioni: **[[http://andreasdalsgaard.blogspot.com/2008/07/openmoko-development-in-5-minutes.html|Openmoko application development in 5 minutes]]**.

Si installano preventivamente i pacchetti:

<code>
apt-get install alien autoconf automake autotools-dev build-essential ccache check curl \
fakeroot gettext intltool libgconf2-dev libglib2.0-dev libtool libxrender-dev mtools uboot-mkimage
</code>

Si scarica la toolchain precompilata dal **[[http://downloads.openmoko.org/developer/toolchains/|repository OpenMoko]]**, esiste la versione i686 e amd64, il pacchetto non è rilocabile e va in **''/usr/local/openmoko''**. Invece di installare il tarball, lo si trasforma in uno pseudo pacchetto .deb facilmente (dis)installabile.

Scegliamo **openmoko-i686-20090323-armv4t-linux-gnueabi-toolchain-openmoko.tar.bz2** (pacchetto per i686, per compilare codice arm su piattaforma GNU/Linux) ed eseguiamo:

<code>
bunzip2 openmoko-i686-20090323-armv4t-linux-gnueabi-toolchain-openmoko.tar.bz2
gzip openmoko-i686-20090323-armv4t-linux-gnueabi-toolchain-openmoko.tar
fakeroot alien -d openmoko-i686-20090323-armv4t-linux-gnueabi-toolchain-openmoko.tar.gz
</code>

Il pacchetto .deb risultante è installabile con

<code>
sudo dpkg -i openmoko-i686_20090323-2_all.deb
</code>

===== Usare la toolchain =====

Prima di compilare qualcosa si deve settare l'environment giusto (''PATH'', ''CPPFLAGS'', ''CXXFLAGS'', ''LDFLAGS'', ecc.):

<code>
source /usr/local/openmoko/arm/environment-setup
</code>

Quindi si usa il compilatore apposito

<code>
arm-angstrom-linux-gnueabi-gcc -o test test.c
</code>

Un'ipotetico **''Makefile''** potrebbe contenere qualcosa del tipo:

<file>
export CC = arm-angstrom-linux-gnueabi-gcc
binary:
        $(CC) -o test test.c
</file>

==== Installazione delle dipendenze ====

Se il programma da compilare dipende da una libreria OpenMoko, bisogna installarla nella toolchain. Prima di tutto si deve impostare i repository da cui attingere in **''/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/etc/opkg.conf''**.

L'impostazione predefinita prevede di scaricare da **unstable**, ecco invece come scaricare i pacchetti da **2008.12**:

<file>
arch all 1
src/gz all http://downloads.openmoko.org/repository/Om2008.8/all
arch armv4t 26
src/gz armv4t http://downloads.openmoko.org/repository/Om2008.8/armv4t
arch om-gta02 31
src/gz om-gta02 http://downloads.openmoko.org/repository/Om2008.8/om-gta02
</file>

Ecco l'esempio di come installare un pacchetto -dev:

<code>
. /usr/local/openmoko/arm/environment-setup
opkg-target update
opkg-target list
opkg-target install gpsd-dev
</code>

L'elenco dei pacchetti disponibili viene salvato in **''/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/usr/lib/opkg/lists/''**.\\
I pacchetti vengono installati sotto **''/usr/local/openmoko/arm/arm-angstrom-linux-gnueabi/''**.

===== Compiling a large project: Navit =====

Remember to improve the page [[http://wiki.navit-project.org/index.php/Navit_on_freerunner|Navit on FreeRunner]].

How to cross-compile a large project like Navit for the OpenMoko/FreeRunner, using a GNU/Linux box and the toolchain.

First of all, edit the ''/usr/local/openmoko/arm/environment-setup'' script and add the followig line:

<file>
export OMTOOL_DIR=/usr/local/openmoko
</file>

After toolchain installation, install (with **''opkg-target''**) some OpenMoko **''-dev''** packages required to compile Navit. Depending upon permissions of ''/usr/local/openmoko/'' directory, you may need root privileges:

<code>
. /usr/local/openmoko/arm/environment-setup
opkg-target list
opkg-target install gpsd-dev
opkg-target install gtk+-dev
opkg-target install libspeechd-dev
</code>

Now we check-out Navit sources from the SVN repository and we make an archive just in case we need the pristine sources in the future:

<code>
svn co https://navit.svn.sourceforge.net/svnroot/navit/trunk/navit
tar zcvf navit-svn-2670.tar.gz navit
</code>

Instead of running the traditional **''./autogen.sh; ./configure''** in the navit source tree, we must run the **''om-conf''** script, which will modify the ''automake'', ''autoconf'' and ''make'' files to run into the OpenMoko toolchain.

Because Navit on the OpenMoko FreeRunner requires some configure options, we will pass them to the script. Run ''om-conf'' from the directory containing the source tree (not inside it):

<code>
om-conf --host=arm-angstrom-linux-gnueabi --enable-avoid-unaligned --enable-avoid-float \
    --enable-cache-size=20971520 --with-saxon=saxon-xslt --with-xslts=openmoko \
    --enable-svg2png-scaling=16,32,48,96 --enable-svg2png-scaling-flag=32,48 \
    navit
</code>

In the example above we used some **''./configure''** options, among them:

**''%%--with-saxon=saxon-xslt%%''**\\ This is because we have the Debian libsaxon-java package, where the executable is called ''saxon-xslt'' instead of ''saxon''.

**''%%--enable-svg2png-scaling=16,32,48,96%%''**\\ For each .svg icon, render a png image of the specified size. Images will be named **''icon_XX_YY.png''**.

**''%%--enable-svg2png-scaling-flag=32,48%%''**\\ Same as above, but only for country flag icons.


It's time to cross-compile:

<code>
cd navit
make
</code>

===== Make an .opk package =====

=== Using the toolchains ===

The OpenMoko toolchain provides the **''om-make-ipkg''** utility. It requires the **directory** name where to execute the ''make install'' and the name of the **control file**:

<code>
. /usr/local/openmoko/arm/environment-setup
om-make-ipkg navit navit-control
</code>

The control file is described [[http://wiki.openmoko.org/wiki/Toolchain#Packaging_your_application|here]].

If you need more control files (e.g. a ''postinst'' or alike) you have to tweak with the ''om-make-ipkg'' script.  Here it is the script I use, it looks for the control files into an **''opkg''** directory, so you have to pass just the directory name containing the source tree.

<code bash>
#!/bin/sh -e

error_exit () {
        echo usage: $(basename ${0}) [app_dir_name] [ipkg_control_file]
        exit 1
}

test x${OMTOOL_DIR} = x && . /usr/local/openmoko/arm/setup-env
. ${OMTOOL_DIR}/arm/scripts/functions
S=${1}
(test x${S} = x || test ! -d ${S}) && error_exit
appname=$(basename ${S})
tmpdir=/tmp/${appname}-ipkg-tmp
test -e "${tmpdir}" && echo Cannot use ${tmpdir} because it already exists. && exit 1
make -C ${S} install DESTDIR="${tmpdir}"
# Copy control files to destination directory.
cp -pr opkg/* ${tmpdir}
ipkg-build -o 0 -g 0 ${tmpdir}
rm -rf ${tmpdir}
</code>

Control files and other files are arranged into the ''opkg'' directory as needed, here it is an example:

<code>
opkg/CONTROL/postinst
opkg/CONTROL/control
opkg/etc/rcS.d/S96overcommit_memory.sh
</code>

=== Using opkg-utils ===

The **[[http://handhelds.org/moin/moin.cgi/Ipkg|ipkg]]** tool is obsolete, OpenMoko uses the **[[http://wiki.openmoko.org/wiki/Opkg|opkg]]** instead, but documentation is scarce.

The current opkg code is in [[http://code.google.com/p/opkg/|Google code]], but you can try this one:

<code>
svn co http://svn.openmoko.org/trunk/src/host/opkg-utils
</code>

and use the instructions of ipkg's website but the software from this checkout. The main script is **''opkg-build''**.

===== Qemu and the GTA02 FreeRunner =====

**WARNING**: this procedure works only for the GTA01 Neo1973, it fails for the GTA02 FreeRunner.

Install the Debian packages **gcc-3.4** and **libsdl1.2-dev**, download the **qemu-neo1973** sources from the [[https://svn.openmoko.org/trunk/src/host/qemu-neo1973|svn repository]]. Run the **''./configure && make''**.

Edit the **''openmoko/env''** file and set current URLs and filenames:

<file>
# Entries for GTA01
kernel_wildcard="uImage-2.6.22.5-moko11+svnr3238-r9-neo1973.bin"
rootfs_wildcard="openmoko-image-fic-gta01.jffs2"
uboot_wildcard="u-boot-gta01*.bin"
download_dir="http://downloads.openmoko.org/distro/obsolete-images/Om2007.11//images/neo1973/"
</file>

Run the **''openmoko/download.sh''** and **''openmoko/flash.sh''** scripts.

For the (failed) attempt to run the GTA02 FreeRunner emulator we need different Qemu parameters and different images:

<file>
qemu_relative="arm-softmmu/qemu-system-arm -M gta02fake -m 130"
# Entries for GTA02, Om2008.12
kernel_wildcard="Om2008.12-om-gta02.uImage.bin"
rootfs_wildcard="Om2008.12-om-gta02.rootfs.jffs2"
uboot_wildcard="gta02v5_and_up-u-boot.bin"
download_dir="http://downloads.openmoko.org/distro/releases/Om2008.12/"
</file>

The **''openmoko/Makefile''** should be changed so the openmoko-flash.base (the NAND image) will be 256 Mb in size:

<file>
# GTA02
$(FLASHIMG):
        # Making an empty/erased flash image.  Need a correct echo behavior.
        $(echo) -en \\0377\\0377\\0377\\0377\\0377\\0377\\0377\\0377 > .8b
        cat .8b .8b .8b .8b .8b .8b .8b .8b > .64b # OOB is 64 bytes
        cat .64b .64b .64b .64b .64b .64b .64b .64b >  .2048b
        cat .64b .64b .64b .64b .64b .64b .64b .64b >> .2048b
        cat .64b .64b .64b .64b .64b .64b .64b .64b >> .2048b
        cat .64b .64b .64b .64b .64b .64b .64b .64b >> .2048b
        cat .2048b .64b > .sec # A sector is 2048 bytes of data + OOB
        cat .sec .sec .sec .sec .sec .sec .sec .sec > .8sec
        cat .8sec .8sec .8sec .8sec .8sec .8sec .8sec .8sec > .64sec
        cat .64sec .64sec .64sec .64sec .64sec .64sec .64sec .64sec > .512sec
        cat .512sec .512sec .512sec .512sec > .2ksec
        cat .2ksec .2ksec .2ksec .2ksec .2ksec .2ksec .2ksec .2ksec > .16ksec
        # Neo GTA02 NAND is 128k sectors big
        cat .16ksec .16ksec .16ksec .16ksec .16ksec .16ksec .16ksec .16ksec > $@
        rm -rf .8b .64b .2048b .sec .8sec .64sec .512sec .2ksec .16ksec
</file>

The **''openmoko/download.sh''** will run, but **''openmoko/flash.sh''** fails with endless errors:

<code>
s3c_nand_read: Bad register 0x20
</code>

May be there are more instructions for the GTA02 in the [[http://wiki.openmoko.org/wiki/Qemu| wiki page]].

FIXME We can manually run the emulator to get the U-Boot prompt, but here we have to partition and flash the NAND manually.

<code>
arm-softmmu/qemu-system-arm -M gta02fake -m 130 \
    -mtdblock openmoko-flash.base \
    -kernel u-boot.bin \
    -serial stdio -nographic -usb -monitor null
</code>