Scratchbox + Maemo 4.0 + Ubuntu Gutsy = Nokia N800

Introduction
Hi, I’m writing this tutorial largely because last time I tried to perform this procedure it was a heck of a lot more complicated. This time it seems to be much simpler, but seeing as my last howto made it into the IRC channel list as a decent howto, I thought it about time I updated it. I wanted to put together a nice clean easy to follow tutorial for getting Scratchbox working to compile and test software for the Nokia N800. Firstly a few disclaimers, this tutorial is right, as of today. Also it is designed for the N800, it may work with the N770/N810, I am not sure. It was also designed for Ubuntu Gutsy, so, I can’t guarantee it’ll work on everyone’s system.

I have linked to all my reference documents at the bottom and will try to tell you when I’m switching from one to the other.

So onto the howto:

Background
First things first, a little explanation into what we are actually doing. We want to create an environment to test and compile code on both x86 and ARM platforms. The N800 runs an ARM processor which means you can’t just grab binaries from the net from your popular debs and hope they’ll work. They won’t. Why? Because each processor has a different instruction set. A compiler tells a process what instruction to run when etc. Obviously trying to run an x86 compiled binary on an ARM processor is going to go nowhere so we have to add a layer of abstraction.

Installing Scratchbox
The instructions below will give you a fully working scratchbox (apophis) with the maemo sdk version 4.0. There is a later scratchbox out there, but for now, we’re going to stick with the more stable/documented one. Traversing the list of documents, we take our first set of instructions from [1]. Basically we are going to install a 4.0 maemo sdk. To begin with, we first need scratchbox installed. The following three commands should be run in your home dir and will grab the scratchbox installer, make it executable, and then run it. Beware, this will lead to downloading over 310Mb of data, so make sure you have enough disk space and bandwidth.

wget 
chmod +x maemo-scratchbox-install_4.0.sh
sudo ./maemo-scratchbox-install_4.0.sh -d

So now we have scratchbox installed and you should be greeted with a message similar to the one below

Installation was successful!
----------------------------

You now have Scratchbox 1.0.8 'apophis' release installed.

Scratchbox cannot be run as user root. Instead, use your normal login
user account. Add additional scratchbox users and sandboxes with the
following command (outside scratchbox with root permissions):

        # /scratchbox/sbin/sbox_adduser USER yes

Running this command will create sandbox environment for that user and
add user to the 'sbox' scratchbox user group.
You will need to start a new login terminal after being added to the
'sbox' group for group membership to be effective.

Login to scratchbox session using the following command (as user):

        $ /scratchbox/login

Refer to scratchbox.org documentation for more information re scratchbox:
http://scratchbox.org/documentation/user/scratchbox-1.0/

pete@ubunt:~$ 

So we need to add a user for scratchbox. This should be your usual user. What happens is that scratchbox sets up multiple build environments for your multiple processors, and within these has a home directory that has the same permissions etc as your home dir. This means that you can easily copy files into your common scratchbox home dir, without requiring root access.

pete@ubunt:~$ sudo /scratchbox/sbin/sbox_adduser pete yes
Adding user `pete' to group `sbox' ...
Done.
Scratchbox user account for user pete added
pete@ubunt:~$ 

You should now log out of your system and log back in again to allow the permissions to propagate, otherwise you are likely to get a permission denied message when executing the next step. Once logged in again, obtain a terminal and use the following.

pete@ubunt:~$ /scratchbox/login

You dont have active target in scratchbox chroot.
Please create one by running "sb-menu" before continuing


Welcome to Scratchbox, the cross-compilation toolkit!

Use 'sb-menu' to change your compilation target.
See /scratchbox/doc/ for documentation.

sb-conf: No current target
[sbox-: ~] > 

Installing Maemo
Having the sbox prompt means you have successfully installed scratch box. We need to now install the maemo SDK into our build environments. Also, it should setup all our build targets during this point. Setting these up manually can be time consuming and annoying, so it’s great to have a script to do it for us. So we first need to exit our scratchbox root, by typing Ctrl+D and then start the sdk installing by;

wget 
chmod +x maemo-sdk-install_4.0.sh 
./maemo-sdk-install_4.0.sh

Notice how I haven’t needed to put a sudo in front of the maemo sdk install script. This is because the build dir is set up to be in your name, and so you will always have privileges to write to it.

During the course of this install script, you will be asked what type of development environment you wish to install. For now, we’re going to go with the default installation type 3. If you’re curious as to what the different types of install are, I have listed them below from resource [1].

• Minimal Rootstrap only. Choose this only if you are going to install all packages you need from repository.
• Runtime Environment. Use this to install and run software inside Scratchbox. Cannot be used for building software.
• Runtime Environment + All Dev Packages. Choose this to get a full development environment.
• Runtime Environment + All Dev and Dbg Packages. You will get a full development environment plus debug symbols for many system components.

You will also be asked to accept the license agreement for the Nokia Binaries. If you object to this, I can’t help you If you agree hit space a few times to read the liecnse agreement and then type I accept before hitting enter.

The great thing about the new installer is that it does most of the work for you. In the old installer there was a lot more to setup, and there were a few problems with getting apt-get updates to work inside the scratchbox environment.

After the installtion has completed, we should be presented with a message similar to the following

Nokia EUSA binaries
-------------------

The package maemo-explicit is a metapackage of Nokia EUSA licensed
binaries which can be installed to scratchbox targets. It is highly
recommended to install this package on both targets to ensure a fully
working system.

If you want to install these, login to scratchbox (see commands above)
and run the command 'fakeroot apt-get install maemo-explicit' for both
armel (CHINOOK_ARMEL) and i386 (CHINOOK_X86) targets.

Happy hacking!

We’d better do what it says. To do this, we need to enter our scratchbox environment again.

pete@ubunt:~$ /scratchbox/login

Welcome to Scratchbox, the cross-compilation toolkit!

Use 'sb-menu' to change your compilation target.
See /scratchbox/doc/ for documentation.

[sbox-CHINOOK_ARMEL: ~] >

Now we need to install the maemo-explicit package as instructed, by running the following.

fakeroot apt-get install maemo-explicit

Once the upgrade has finished, you should switch to the other build target by invoking the sb-menu command. This will yield a menu system, using the arrow keys, select the option Select : Activate a target, and choose the environment you haven’t yet updated, in our example CHINOOK_X86. Now just run the above command again and we should have both environments setup ready to go.

Testing it graphically
Ouch, we’re almost there I promise, switching to [2]. We’re now going to load up another terminal in order to test the graphical running of the maemo system, and to compile a test program and run it in the ARMEL target. In this new terminal window, we simply need to run two things, first;

sudo apt-get install xserver-xephyr

This will install the nested X server that is required to test the graphical running of the N800 emulation. The second is to actually start the Xephyr server by invoking this command.

Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -extension Composite

This starts a new nested Xephyr server on display :2, which is actually a new window. You can move this to one side for the time being as we have yet to pipe anything to it. Start up a new terminal window because we require the creation of a file to test the compilation. We’re going to create it in your home directory and then copy it to your build environment, so that you get used to where files in your build environments are placed. Create a file and copy and paste in the following;

#include 
#include 
#include 

int main(int argc, char *argv[])
{
    /* Create needed variables */
    HildonProgram *program;
    HildonWindow *window;
    GtkWidget *button;

    /* Initialize the GTK. */
    gtk_init(&argc, &argv);

    /* Create the hildon program and setup the title */
    program = HILDON_PROGRAM(hildon_program_get_instance());
    g_set_application_name("Hello maemo!");

    /* Create HildonWindow and set it to HildonProgram */
    window = HILDON_WINDOW(hildon_window_new());
    hildon_program_add_window(program, window);

    /* Create button and add it to main view */
    button = gtk_button_new_with_label("Hello!");
    gtk_container_add(GTK_CONTAINER(window), button);

    /* Connect signal to X in the upper corner */
    g_signal_connect(G_OBJECT(window), "delete_event",
      G_CALLBACK(gtk_main_quit), NULL);

    /* Begin the main application */
    gtk_widget_show_all(GTK_WIDGET(window));
    gtk_main();

    /* Exit */
    return 0;
}

Save the file as maemo_hello.c. We will now close the editor down and copy the file. In this example the file is in my home directory and I’m using a new terminal window to copy because I want to leave our scratchbox terminal window in scratchbox, and our Xephyr window ready for use.

cp maemo_hello.c /scratchbox/users/pete/home/pete/

Notice where your scratchbox home dir is now. If you run a ls command in your scratchbox window, you should see the maemo_hello.c file appear in your home dir.

[sbox-CHINOOK_X86: ~] > ls
MyDocs                           maemo-sdk-rootstrap_4.0_armel.tgz
maemo-sdk-nokia-binaries_4.0     maemo-sdk-rootstrap_4.0_i386.tgz
maemo-sdk-nokia-binaries_4.0.sh  maemo_hello.c
[sbox-CHINOOK_X86: ~] > 

So, now using the sb-menu command from before, make sure you are in the ARMEL target. This means that any binaries we compile at the moment are going to be made speficially for the N800 and without the help of scratchbox, we couldn’t run them on our x86 processor.

gcc -o maemo_hello maemo_hello.c `pkg-config --cflags gtk+-2.0 hildon-1` -ansi -Wall `pkg-config --libs gtk+-2.0 hildon-1`

This will compile the maemo_hello.c file to the binary file maemo_hello. Please note that this binary file can now be copied across to any N800 machine and run without any problems. Now all we have to do is test it in our scratchbox environment. The following few commands will do that. Still in our scratchbox terminal, first we export the DISPLAY variable to have a value of :2, which will point to our Xephyr server, next we run the startup script for the maemo testing environment.

export DISPLAY=:2
af-sb-init.sh start

Here you should see some text whizz by and it’ll appear that you can’t use that window as it’s occupied. Wait till it’s finished, probably with a line like;

hildon-desktop[6545]: GLIB WARNING ** default - Plugin desktop file not found, ignoring plugin
hildon-desktop[6545]: GLIB WARNING ** default - Plugin desktop file not found, ignoring plugin

Then press the enter key and you’ll get your scratchbox prompt back. Notice also that our Xephyr window now has graphical goodness. This means that the scratchbox instance is correctly running on ARMEL and is piping it’s output to the Xephyr server. We shall now invoke our testing line.

run-standalone.sh ./maemo_hello

The run-standalone.sh script sets up some important environment variables and themes.

Signing off
You should end up with an app that takes up the whole available window and says Hello in the middle.

There you have it. A dev environment set up and ready to use. Only took an hour From talking to some people in the #maemo channels, most don’t even bother with the x86 build environment. As the installer provides it, I feel it useful to set it up and get it running as well. Please read the links cited, and look at the maemo.org website. I hope this has helped people out. Took me several days to get a working system initially, but in doing this tutorial, took me a little under and hour.

References
[1]
[2] http://maemo.org/development/documentation/tutorials/maemo_4-0_tutorial.html
[3]