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 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.
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:
sbrsh
(not covered in this material).
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 scratchbox.org.
In this material we'll be using only the Scratchbox capabilities that are necessary to use the maemo SDK.
Scratchbox terminology:
apt-get
to install the "rest of" the SDK after extracting the base rootstrap.
There is a special feature that the kernel needs to support in order for the instruction emulator in sbox to work properly. This is the binfmt_misc-feature. It is normally built as a module, so verify that it is loaded in Linux (no root access needed for this):
user@system:~$ lsmod | grep binfmt binfmt_misc 12936 0
If you do not see a line of output, attempt to do a modprobe binfmt_misc as root (or with sudo). If this still does not work, you will have to find the module somewhere, or even recompile the kernel. On most Debian-based systems (Debian, Ubuntu), the module is included, so there should not be any problems, unless you have built your own kernel. It is also possible that the feature has been built inside the kernel directly, instead of a module.
Also a pseudo X server should be installed to act as an X client to the real system. It will be necessary to run the applications that are developed, after installing the SDK.
There are a few options for this purpose, but this material will cover the usage of Xephyr. Xephyr is a Kdrive-based X server/client that can emulate 16-color depth for its clients even if it is acting as a client to an 24-bit depth real X server. It also implements modern X protocol extensions.
The concept of having a program that is both X server and a client may seem weird. However, there is no reason to worry, as it is a tested technology and works quite well. If, on the other hand, it does not make any sense, revisit the X Window System introduction in the previous chapter.
To install Xephyr:
sudo apt-get install xserver-xephyr
on your real Linux system.
dpkg -l | grep xephyr
(as non-root).
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:
user@system:~$ sudo sh ./maemo-scratchbox-install_X.X.sh -u user
The -u user
option is used, so that Scratchbox will add the user account "user" automatically into the group that is allowed to use Scratchbox.
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; this 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_X.X.sh
Running this script will display the end user license agreement. Pressing Enter key to accept the license presents you with package selection dialog.
You are presented with four options of installing SDK:
By default, option 3 is selected.
N.B: The SDK installer will always download and install the minimal rootstrap, but will install additional packages using apt-get based on your choice.
In the next dialog, you can choose to install closed Nokia binaries or not.
Selecting 'yes' will run the Nokia binaries installer script which will display the EUSA(End User Software Agreement). If you accept the agreement, the installer script will extract the Nokia binaries into a folder under the user's home directory inside scratchbox. It will also configure the /etc/apt/sources.list file in the scratchbox targets to make this 'local repository' visible to the Debian apt tools.
In the next dialog, a summary of your selections so far and the default settings are listed.
Selecting 'Continue' will initiate the SDK installation process. If the selection summary is not OK, you can cancel the process and re-start the SDK installation script.
After it's successful execution, you will have 2 scratchbox targets ready for use:
DIABLO_X86
: Suitable for software development and testing.
DIABLO_ARMEL
: Suitable for building software for the ARM architecture.
The Nokia binaries are not installed by default but just made available. If you wish to install all of them , then execute the following command inside the scratchbox targets:
[sbox-DIABLO_<target>: ~] > fakeroot apt-get install maemo-explicit
N.B. The installer script by default will prompt the user to install the Nokia binaries, which are not open source. To disable this feature, please use -f command line parameter for the script. For more options, use the command line help option.
user@system:~$ sh maemo-sdk-install_X.X.sh --help
The rootstrap files are available in the same location as the automatic install scripts (for maemo 4.1 SDK they can be found at maemo.org).
It is necessary to download the minimal rootstraps for i386 and arm, so the filenames will be as follows:
For other versions of the SDK, the exact path names above will need to be adjusted (please consult the SDK installation instructions).
Do not extract the downloaded files. They have to be moved under a location where Scratchbox setup tools can find them (/scratchbox/packages/):
user@system:~$ sudo mv /tmp/download-location/maemo-sdk-rootstrap* \ /scratchbox/packages/
You are 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.
The first step is to log in on the Scratchbox environment:
By default, Scratchbox will activate the same target that was used previously, but since this is the first time Scratchbox is used, there is no target to activate. One can be built with sb-menu:
[sbox-: ~] > sb-menu
Normally the tool would display all configured targets in a list, but since there are none, the dialog is empty. Select "NEW" in order to create a new target.
cs2005q3.2-glibc2.5-i386
).
debian-etch
, maemo3-tools
and perl
. Do not select cputransp for the X86 target. Select each of them in a row and then press "DONE".
C-library
, /etc
, Devkits
and fakeroot
. Other tools can be installed later from the maemo SDK repository (or local mirror of the repository).
Selecting the target will restart the Scratchbox session and if everything went well, you are now left with a very minimal maemo SDK environment:
Shell restarting... [sbox-DIABLO_X86: ~] > arch i686 [sbox-DIABLO_X86: ~] > dpkg -l | grep maemo-repository ii maemo-repository 4.1-1 Configuration for maemo repository.
[sbox-DIABLO_X86: ~] > apt-get update
[sbox-DIABLO_X86: ~] > fakeroot apt-get install maemo-sdk-dev
Using fakeroot is important in the above command so that the package install scripts think that they are 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 concerned. This can be ignored by accepting installation of unverified packages.
After apt-get
finishes installing all the packages, the SDK installation is ready.
When you are finished with sbox, you need to logout. This is done by terminating the command shell with the exit command, or by using logout.
If the automatic install process was used, the ARMEL target is already available (as DIABLO_ARMEL), and the following steps are not necessary.
Creating the ARMEL target requires creating a new target in Scratchbox, using the same steps that were taken for the X86 target.
Here is how the ARMEL target install process differs from the X86 (described above):
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.