Iliad unofficial toolchain

How to set-up the iliad unofficial toolchain (antartica's)

After following this tutorial, you will get:

• A cross compiling environment
• An emulator to compile and test the programs (scratchbox, which simulates native compiling; no cross-compiling headaches, it's done transparently for you)
• some scripts to aid in downloading/patching/compiling programs from debian for the iliad
• some scripts to aid in preparing packages for the iliad
• the patched libX11 so that x programs refresh the screen automatically when executed in the iliad

Prerequisites:

1. A PC (x86)
2. A Debian Linux distribution installed, preferably Debian 3.1, but Ubuntu should also work (for windows users, the recommended method is to use VMWare Player and download the Sarge image from VMWare appliances page; for Mac users, one choice is parallels, for other linux distributions you will have to set-up a chroot environment)
3. An internet connection
4. Patience

Method

1. Become root, or use sudo:

$ su -
password:
#

2. Install the development files

# apt-get install build-essential wget python

3. Add the scratchbox repositories:

# echo "deb http://scratchbox.org/debian/ apophis main" >> /etc/apt/sources.list
# apt-get update

4. Download the toolchain and the "fix" script

# wget http://projects.mobileread.com/iliad/projects/toolchains/scratchbox-toolchain-arm-softfloat-gcc3.4.2-glibc2.3.3_20061031-2_i386.deb
# wget http://projects.mobileread.com/iliad/projects/toolchains/make-hardlinks

5. Install the package

# dpkg -i scratchbox-toolchain-arm-softfloat-gcc3.4.2-glibc2.3.3_20061031-2_i386.deb
# sh ./make-hardlinks

This will output warnings about dependency problems. Ignore for now.

6. Install the rest of the packages -- this will fix the dependency problems.

# apt-get -f install

7. Configure a new user in scratchbox that uses the new toolchain

# sb-adduser your_user (if this fails, try /scratchbox/sbin/sbox_adduser instead)
# su your_user (on Ubuntu being su is not allowed)
$ sb-menu (if this fails, exit the current session and log-in into the machine again, then try again -- this is to force it to reload the env. variables for your user)
Select action: Setup 
Install into target: <NEW>/Create a new target
Enter name for the new target: iliad
Select compiler: arm-linux-iliad-softfloat
Selected devkits: cputransp
Selected devkits: cputransp debian (or debian-yourdebianversion, for example debian-etch)
Selected devkits: cputransp debian perl
Selected devkits: cputransp debian perl DONE
Select CPU-trnasparency method: qemu-arm (also works qemu-arm-0.8.2-sb)
Do you wish to extract a rootstrap on the target?: No
Do you wish to install files to the target?: Yes
Install files to target: mark all as [X], then OK
Do you wish to select the target?: Yes
Select action: Exit

8. Enter into the scratchbox environment

$ scratchbox

9. Configure the package config variables in the user

sbox$ echo "export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig" >> .bash_profile
sbox$ source .bash_profile

10. Download and install the precompiled libraries

sbox$ cd /
sbox$ wget http://projects.mobileread.com/iliad/projects/toolchains/toolchain-iliad-usr-local_20061204-1.tar.gz
sbox$ tar -xvzf toolchain-iliad-usr-local_20061204-1.tar.gz
sbox$ cd

11. Install the helper scripts

sbox$ wget http://projects.mobileread.com/iliad/projects/toolchains/dependencies-helper_20080718-1.tar.gz
sbox$ tar -xvzf dependencies-helper_20080718-1.tar.gz
sbox$ ln -s dependencies-helper/*.sh .
sbox$ wget http://projects.mobileread.com/iliad/projects/toolchains/packing-helper_20061214-2.tar.gz
sbox$ tar -xvzf packing-helper_20061214-2.tar.gz

12. If you are having problems running apt-get update from within scratchbox see

 http://lists.maemo.org/pipermail/maemo-developers/2007-May/010257.html

13. All done! :-)

example: compiling a program

1. Enter the scratchbox environment.

$ scratchbox

2. Create a directory for the new app.

sbox$ mkdir src.xmpuzzles
sbox$ cd src.xmpuzzles

3. Use the scripts to compile and install the program (the -u is to tell the scripts to not try to compile/install it; we will do that ourselves; for libraries, you will surely want to omit the -u).

sbox$ ../dl-and-install.sh -u xmhexagons
Press ENTER when prompted

4. Wait until it downloads the program and patches it.

5. Enter the appropiate directory (read the last line echoed).

sbox$ cd xpuzzles-7.2.4

6. Skim though the readme file and follow the instructions to build it (alternatively, peek at debian/rules and see how the debian folks build the program): If there is no readme, it usually compiles with a "./configure && make". In this case:

sbox$ head -20 xpuzzles.README
sbox$ make -f xpuzzles.Makefile configure
sbox$ make -f xpuzzles.Makefile

7. That's it. you should have the new executables prepared for the iliad. Now it's time to make a package if you plan to use them, or fire up the VNC server to test them in the emulator... Anyway, if you have an X display (e.g., you have X configured and installed), you can try them right now:

sbox$ DISPLAY=:0 ./xpyraminx/xpyraminx

example: packing a program

We will assume for this example that you have followed the "compiling a program" section so that you have xmpuzzles compiled for the iliad, ready to be packed.

Prior to following this example, please check with the installation method that you have the last version of packing-helper installed (item 11 of the installation method).

1. Change to the directory in which you downlaoded the sources and have the program compiled

sbox$ cd ~/src.xmpuzzles

2. Create a directory for the new program, with the name that you want it to be listed when in the iliad

sbox$ mkdir xhexagons
sbox$ cd xhexagons

3. Copy the compiled executable to the current directory

sbox$ cp ../xpuzzles-7.2.4/xhexagons/xhexagons .

4. Generate the libraries directory with re required libraries not present in the iliad:

sbox$ ~/lib-gen.sh xhexagons

5. Generate a run.sh script to be able to launch this program in the iliad (optionally, edit the run.sh file if the program has special runtime or command-line requirements, for example, setting the HOME variable to `pwd` to don't pollute the iliad flash or setting some program parameters):

sbox$ ~/run-gen.sh xhexagons

6. Finally, pack the program in a tar.gz that we will install in the iliad:

sbox$ cd ..
sbox$ tar -cvzf xhexagons-0.7.4_iliad-0.1.tar.gz xhexagons

7. Untar the package in the iliad and test it.

testing applications using VNC

Note: this part needs to be tested

One-time setup

To make the environment more iliad-like, we will need the iliad apps:

$ su -
password:
# cd /scratchbox/users/your_user
# mkdir iliad
# cd iliad
# wget http://projects.mobileread.com/iliad/projects/os/filesystem.28.tar.gz
# tar -xvzf filesystem.28.tar.gz
# echo '#!/bin/sh' > iliad.sh
# echo 'LD_LIBRARY_PATH=/iliad/lib:/iliad/usr/lib /iliad/lib/ld-linux.so.2 $@' >> iliad.sh
# chmod 755 iliad.sh
# exit

Launching the vnc server and client

First start an VNC server with X support (i.e. the UNIX vncserver) in your machine. In Linux this can be done with:

$ vncserver -ac -geometry 768x1024 -depth 8 :1

Then export the DISPLAY in the scratchbox environment to that vnc and start the basic apps (that is what we have installed in the "one time setup" section):

sbox$ export DISPLAY=ip_of_vncserver:1
sbox$ /iliad/iliad.sh usr/bin/matchbox-window-manager -use_titlebar no -use_cursor no &
sbox$ /iliad/iliad.sh usr/bin/pageBar &
sbox$ /iliad/iliad.sh usr/bin/matchbox-panel --size 39 --no-menu --bgcolor White &

Testing the app

1. Open your vncviewer of choice (for example realvnc) and connect to ip_of_vncserver:1 2. In scratchbox, export the display to the vncserver and execute your app:

sbox$ DISPLAY=:0 ./xpyraminx/xpyraminx

And test :-).

Note that this doesn't work for apps that use the /dev/fb0 directly, bypassing XFBDev (as scribble), but for self-compiled apps and xpdf, it works ok. Also note that there is no simulation of hardware buttons.

Possible problem using "dl-and-install.sh" script

I noticed when following these instructions that it is possible for scratchbox to not find the server 'packages.debian.org'. A post in the MobileRead forums shows the answer for this ([post describing solution]) but I have described the relevant fix having installed on Ubuntu Hardy Heron below:

sbox$ cd /etc/
sbox$ touch resolv.conf
sbox$ nano resolv.conf

Add the text 'nameserver your.dns.address.here' without quotes and replacing the end of the line with the appropriate DNS IP address value. For me it was:

nameserver 10.0.2.3

After doing this, scratchbox will be able to find the server and hence download the required files.

TODO

• It would be nice to have a prepackaged VMWare Appliance in the spirit of the one available for maemo: [Maemo Development Appliance]

References

• [How-to: build a toolchain for the iliad using crosstool (MobileRead forum thread)]
• Notes about building a toolchain for the iliad using crosstool wiki page updating the notes from tha above post.
• [MobileRead thread about this page]
• [Crosstool homepage]
• [ScratchBox homepage]