Getting started

This chapter covers the pre-requisites and installation of the development environment. The maemo SDK consists of libraries and tools enabling the development of applications for maemo and Internet Tablets. This SDK must be installed into an development environment called Scratchbox in order for it to be useful.

At this point, you should check the maemo training wiki pages (http://maemo.org/community/wiki/maemoTraining) maintained by maemo community. They might contain some information which affects the SDK installation process. Notice that the information in maemo wiki is not verified by Nokia and thus Nokia cannot be responsible of that information.

We'll start by installing Scratchbox first and then proceed by installing the maemo SDK inside Scratchbox. The next chapter covers testing of the installation using simple text and graphical programs.

Installing the SDK can also be done by using automatic installation scripts, using which is covered in the SDK installation instructions (part of the SDK). This material will cover installation in a more step-by-step fashion, so that you may easily create custom Scratchbox targets in the future.

What is Scratchbox?

Now that you've seen what both Internet Tablet and applications designed for maemo are made of, you might be wondering how to write your own applications. If you've used the various GNU tools before you also might be wondering how all the different versions of tools and libraries are handled during development.

Enter Scratchbox, a specially packaged "sandbox" environment which provides the necessary tools and also isolates your development efforts from your real Linux system. Scratchbox also makes it easy to do cross compiling which means building your software into a binary format that is executable in your target device.

The name "Scratchbox" comes from "Linux from scratch" + "chroot jail" (sandbox). This also tells you something about its implementation and intended use. While working inside Scratchbox, you'll be running programs in a changed root environment (chroot). In Linux systems it's possible to change the part of file paths that a process will see. Scratchbox uses this mechanism on start to switch its root directory (/) to something else than the real root. This is part of the isolation technique used. Because of this, the environment is called a sandbox, a private area where you can play around without disturbing the environment and without all the mess that real sand would cause. The other parts of the isolation technique are library call diversions (using LD_PRELOAD), wrapping of compiler executables and other commands.

Scratchbox:

Is a software package to implement development sandboxes (for isolation)

Contains easy to use tools to assist cross-compilation

Supports multiple developers using the same development system (not covered in this material).

Supports multiple configurations for each developer.

Supports executing target executables on the hardware target, via a mechanism called sbrsh (not covered in this material).

Supports running non-native binaries on the host system via instruction set emulators (Qemu is used).

Beside these main features, it's possible to develop your own software packages that can be installed and used inside a Scratchbox environment. Scratchbox also includes some integration for Debian package management, so that once we have setup our source files correctly and write a couple of configuration files, we can create binary distribution packages for various architectures (similar to .msi-files in Windows, or .rpm-files in Fedora Core, RHEL and SUSE). These tools are also used to provide the environment with a packaging database so that we can install other development packages over the Internet when we need them (by using standard Debian package management tools).

The Internet Tablet also uses a similar packaging system, and this means that packages built using Scratchbox and the SDK can be installed on the real device.

Scratchbox is licensed under the GPL and it's open for outside contributions. For an in depth coverage on Scratchbox capabilities please see http://www.scratchbox.org/.

In this material we'll be using only the Scratchbox capabilities that are necessary to use the maemo SDK.

Scratchbox components

Before installing Scratchbox, we need to cover some terminology that it uses in its documentation. For most of the time Scratchbox will be abbreviated as sbox from now on.

Scratchbox terminology:

core package: package that contains the core tools implementing sbox. These also include a host compiler (gcc) that can be used to build additional tools for sbox.

libs package: contains the necessary libraries for the core to operate.

devkit: a package for sbox that contains additional development tools. We'll be interested in 4 devkits (listed later).

toolchain: compilers, linkers and tools for a specific target. We'll be needing two, but we'll use the x86-one for now.

target: the active toolchain and configuration we're using currently. A target uses a selected toolchain and contains a filesystem to use and related configuration. You can have multiple targets, even if they all use the same toolchains. This makes it easy to try something different, or start a parallel target to test things from scratch.
Note that an sbox target doesn't technically mean the same thing as the physical target device you might have (Internet Tablet).

rootstrap: a target root filesystem image that can be used as a basis for further development. Rootstraps normally contain the necessary files for some specific development target, but sometimes only act as a starting point for the target. There is a rootstrap for developing applications for maemo, and we'll refer to it with "maemo SDK" for the rest of the material. The maemo SDK rootstrap is also slightly special in that one normally will also run apt-get to install the "rest of" the SDK after extracting the base rootstrap.

Prerequisites

Before continuing, you should quickly review the installation instructions of the maemo SDK.

There is a special feature that your kernel needs to support in order for instruction emulator in sbox to work properly. This is the binfmt_misc-feature. It normally is built as a module so verify that it is loaded in your Linux (no root access needed for this):

user@system:~$ lsmod | grep binfmt
binfmt_misc 12936 0

[ Verifying whether binfmt_misc is loaded ]

If you do not see a line of output, attempt to do a modprobe binfmt_misc as root (or with sudo). If this still doesn't work, you'll need to find the module somewhere, or even recompile the kernel. On most Debian-based systems (Debian, Ubuntu) the module is included so you shouldn't run into problems unless you've built your own kernel. It is also possible that the feature has been built inside your kernel directly instead of a module.

You should also install a pseudo X server that can act as an X client to your real system. It will be necessary to run the applications that we develop after installing the SDK.

There are three options:

Using Xephyr, a Kdrive based X server/client that can emulate 16-color depth for its clients even if it's acting as a client to an 24-bit depth real X server. It also implements modern X protocol extensions. This material will only cover Xephyr.

Using Xnest, which is an older version of the subject. Requires your real X server to be at the same depth that it is simulating to its clients.

Using Xvnc which is an X server that can be connected to using a VNC client. Using Xvnc is not covered here, but its use should be very close to using Xnest.

If the concept of having a program that is both X server and a client seems weird, don't worry, it is a tested technology and works quite well. If on the other hand it doesn't make any sense, revisit the X Window System introduction in the previous chapter.

Automatic install of Scratchbox

The preferred way to install the Scratchbox is to use the automated installation script. Manual installation of the Scratchbox is described here for educational purposes, and for situations where the automatic installation script fails.

Quick installation of Scratchbox on a Debian system with the automated install-script:

Manual install of Scratchbox

Since sbox is a environment that is meant for general use, we find that there are many distribution methods to choose from. We'll choose to download the sbox Debian packages before installing them. This is a suitable method when doing "offline" installs of the SDK.

scratchbox-devkit-cputransp_*_i386.deb. Contains the "CPU transparency" support, including the instruction set emulator (Qemu).

Note that there are various other files available as well. The exact version number has been substituted with an asterisk character here as version numbers can vary as the product is updated. You may also opt to download the doctools devkit if you plan to build documentation for open source projects.

Once you've finished, be sure to note the location where you saved the files to. We'll use /tmp/download-location/ from now on in the material to refer to the path containing the downloaded packages.

Should you ever need to temporarily stop Scratchbox from doing its magic, run sudo /etc/init.d/scratchbox-core stop. To start Scratchbox again, use sudo /etc/init.d/scratchbox-core start. Normally stopping and starting is not required in Debian-based systems as sbox is started automatically on system boot. However, it is useful to know how to stop it when trying to fix problems that might be caused by problems in the isolation code of Scratchbox (or removing Scratchbox).

The next step is to add users to Scratchbox as a root-user (we use sudo-command to get root privileges):

Check using the id -command whether your account is part of the sbox-group after installation. If sbox is not listed in your groups, you'll need to relogin into your system. Re-verify with id if in doubt.

Automatic install of the maemo SDK

The preferred way to install the the maemo SDK is to use the automated installation script. In some cases using a manual process is more suitable, and is covered later. Installing the SDK in an "offline" environment is officially unsupported, but possible as well.

Quick installation with automated install-script:

user@system:~$ sh maemo-sdk-install_4.0.sh

[ Running the automatic install script for maemo 4.0 SDK ]

Note that the installer script will by default also load the Nokia binaries which are not open source. If you wish to disable that feature, please use -f command line parameter for the script. The automatic installer will display the license (Nokia EUSA) and ask before proceeding.

The binary packages installer will extract the files under your home directory within Scratchbox and modify the apt source paths so that the packages will be available within the targets.

There's also the command line option --help which you might want to use if you wish to use the automatic script, but have a non-default environment.

Once you start the script, it will ask you what kind of install you want to do. It will always download the base rootstrap file, but will run apt-get within the targets which will load additional packages based on your choice.

[ Select what additional package sets will be downloaded after rootstrap is installed. ]

The "Runtime Environment + All Dev Packages" choice will cause apt-get install maemo-dev-sdk to be run after the rootstrap has been downloaded and extracted.

Once the automatic script will complete, you will have two targets:

CHINOOK_X86: Suitable for using for software development and testing.

CHINOOK_ARMEL: Suitable for building software for the ARM architecture.

Manual install of the maemo SDK

In order to install the maemo SDK manually, we'll first have to download the rootstrap files necessary. There will be two: one for the X86 target, and the other one for the ARM target (we'll call it ARMEL to differentiate between an older version of the binary API from the newer one).

The rootstrap files are available in the same location as the automatic install scripts (for maemo 4.0 SDK they can be found at http://repository.maemo.org/stable/chinook/). You may also opt to download the Nokia binaries installer (it's the large shell script which contains the Nokia EUSA license). This material does not require the Nokia binaries.

You'll need to download the SDK for i386 and arm, so the filenames will be as follows:

i386/maemo-sdk-rootstrap_4.0_i386.tgz for the X86 version

armel/maemo-sdk-rootstrap_4.0_armel.tgz for the ARMEL version

For other versions of the SDK, you will have to adjust the exact path names above (please consult the SDK installation instructions).

Do not extract the downloaded files. Instead they will have to be moved under a location where Scratchbox setup tools can find them (/scratchbox/packages/):

You're now ready to setup your first sbox target. Scratchbox comes with a simple menu driven tool (sb-menu) which can be used for this. The other option would be using a command line driver tool (sb-conf), but using the menu driver tool is easier.

We'll start by logging in into the Scratchbox environment:

user@system:~$ /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-: ~] >

By default Scratchbox will active the same target that we used previously, but since this is the first time we're using Scratchbox, there's no target to active. Let's build one with sb-menu:

[sbox-: ~] > sb-menu

This will start the tool, and your screen should resemble more or less this:

[ Main menu of the sb-menu tool ]

Select "Setup" in order to create a new target:

[ Setting up the first target ]

Normally the tool would display all configured targets in a list, but since we don't have any, the dialog is empty. Select "NEW" in order to create a new target:

Using the same names as the automatic install script uses allows you to use the Nokia binaries installer later. Type CHINOOK_X86.

Since our first target will be for X86 environment, select the i386 compiler version.

Next, you will need to select all the devkit packages that you want to enable for the new target. You will need debian-etch, maemo3-tools and perl. Do not select cputransp for the X86 target. Select each in a row and you should then have a display similar to this one (the selections are listed above the list of devkits):

Since we didn't select the cputransp devkit in previous step, selecting the CPU transparency becomes an easy choice:

This concludes the target-specific tool choices, but we're not quite done yet. We'll next need to select a rootstrap package to extract into the target (select Yes):

And since we already downloaded the rootstraps and copied them to the proper location, select File:

Using TAB arrows, navigate to the proper rootstrap file (the one that ends with i386) and select it by pressing space and then press ENTER to go forward:

Unpacking the rootstrap will not take long, and soon after that, you will see the following dialog:

Select Yes (even if it's not entirely obvious what the question means) and then select the C-library, /etc, Devkits and fakeroot. Other tools can be installed later from the maemo SDK repository (or local mirror of the repository):

After extracting the selected files from the rootstrap, the target is now ready. You should next opt to select the target (so that becomes active and will be default target from now on):

Selecting the target will restart the Scratchbox session and if everything went well, you're now left with a very minimal maemo SDK environment:

[ Checking that the architecture is correct and that the minimal rootstrap has been installed ]

In order to complete the SDK installation, you will have to fetch the package list and then install the maemo-sdk-dev meta-package. The package depends on a lot of other packages and all of them will be downloaded into the target. The number of packages is quite significant, so reserve some time for this step. This step will require a working Internet connection (or doing DNS-redirection into a local copy of the repository).

Using fakeroot is important in the above command so that the package install scripts think that they're running as the root user. Otherwise the installation phase will fail with errors. Modern Debian style repositories are signed with GPG keys in order to prevent tampering with the repository contents. The maemo repositories however do not use this convention and this makes apt-get slightly unhappy. We ignore this by accepting installation of unverified packages.

After apt-get finishes installing all the packages, the SDK installation is ready.

When you're finished with sbox, you need to logout. This is done by terminating the command shell with the exit command or by using logout.

Manual install of the ARMEL target

If you installed the X86 target manually (above), at some point you'll also want to create the ARMEL target so that you may build your software for the Internet Tablets. You may also defer this step until you're ready to do cross-building for Internet Tablets.

If you used the automatic install process, the ARMEL target is already available (as CHINOOK_ARMEL) and you don't need to do any of the following steps.

Creating the ARMEL target requires creating a new target in Scratchbox, using the same steps that were done for the X86 target.

Here is how the ARMEL target install process differs from the X86 (described above):

Stop any processes you may have running on the X86 sbox target (sb-conf killall)

Then start sb-menu as you did with the X86 target:

Name your target CHINOOK_ARMEL (for compatibility)

You will need to select the arm version of the compiler.

You will need to select the cputransp devkit and then select qemu-arm-0.8.2-sb2 as the CPU transparency method (instead of none that was used for X86).

You will need to select the arm version of the maemo SDK base rootstrap.

The apt-get command remains exactly the same, as do all of the other steps.

You may wish to verify the target by using the steps below ("Testing Scratchbox"), at least build the hello world program and verify the architecture of the resulting executable with file command.