All rights reserved.
Project: maemo 4.1.2 Diablo Development Platform
Baseline: OS2008 5.2008.43-7
This INSTALL.txt file explains how to install and set up the maemo 4.1.2
development environment on your computer. This document is
targeted for maemo developers.
1. SCRATCHBOX APOPHIS R4 INSTALLATION
This chapter is for developers who do not have Scratchbox
Apophis R4 installed on their computer yet.
You can install Scratchbox in two ways:
- using the installer script (recommended), or
It is strongly advised to use the Scratchbox installer script as
explained in chapter 1.1. If for some reason you want to, or need
to install Scratchbox manually jump to chapter 1.2.
1.1 Installing Scratchbox using the installer script
This maemo release includes an installer script which will download
and install the required version of scratchbox to your host
The installer script can be found from this URL:
To install scratchbox, first download the script (from the link
mentioned above) to your host computer and run the
maemo-scratchbox-install_4.1.2.sh as user root:
$ chmod a+x ./maemo-scratchbox-install_4.1.2.sh
$ sudo ./maemo-scratchbox-install_4.1.2.sh
This is the easiest way to install scratchbox, and it is also the
recommended way. Follow the instructions given by the script.
Running the script will not modify any files outside its given install
path. Downloaded files are temporarily stored in /tmp directory.
These can be safely removed after the installer has completed.
On Debian based distributions: the install script will use Debian
packages. Packages install to the default path, /scratchbox.
On any other Linux distribution: the install script will use .tar.gz
files which can be installed to any given path. Scratchbox installation
should be separate from host system's tools, e.g. to /scratchbox or
Specify users to be added to scratchbox users with '-u USER'
option. Run the command 'newgrp sbox' or start a new login terminal after
being added to the group for group membership to be effective.
After the installer has finished you should have a working
Scratchbox environment ready.
In a rare situation, if the installer can not work properly on your
system you may have to do a manual installation. This is explained
in chapter 1.2 below.
1.2 Installing Scratchbox Apophis manually
If you have installed Scratchbox with the script mentioned above in
chapter 1.1 then you can skip this chapter.
You need to install the following packages:
These packages can be downloaded from the scratchbox.org server.
Detailed instructions on how to install Scratchbox to your computer
1.3 Known limitations of scratchbox:
Scratchbox doesn't work when VDSO support is enabled in the host's kernel.
The status of VDSO support can be verified from the /proc filesystem.
Only values 0 and 2 are compatible with scratchbox.
Depending on the kernel version the VDSO support can most likely be found
in /proc/sys/kernel/vdso or /proc/sys/vm/vdso_enabled.
You can disable it for the current session by echoing a 0 to the given
location under the /proc filesystem as root.
For example on Ubuntu Hardy/Intrepid:
$ echo 0 | sudo tee /proc/sys/vm/vdso_enabled
64 bit Linux kernels starting from version 2.6.25 enable VDSO by default and
do not offer a /proc filesystem option to turn it off. Notably Debian Lenny
and Fedora9 are using such kernels. However, a kernel boot parameter has been
verified to work on a 64 bit system. If you run into this problem, please
add 'vdso32=0' to your kernel boot parameters.
The QEMU used by Scratchbox is not compatible with mmap_min_addr value
higher than 4096. This feature is not enabled in all kernels and the
default value may differ. You can check the value of the mmap_min_addr
from the /proc filesystem. The location for this setting is
You can set a desired value for the current session by echoing it to
the given location as root.
For Ubuntu Hardy/Intrepid:
$ echo 4096 | sudo tee /proc/sys/vm/mmap_min_addr
The fakeroot used in Scratchbox uses local tcp sockets to
communicate with the faked daemon. During build time a package may
handle so many files that the system runs out of sockets.
In these cases you will see the following kind of log writings during
the build process:
libfakeroot: connect: Cannot assign requested address
libfakeroot: connect: Cannot assign requested address
You can increase the number of allowed local port allocations by
modifying a setting under the /proc filesystem as root. The
location for this setting is /proc/sys/net/ipv4/ip_local_port_range.
Example for Ubuntu Hardy/Intrepid:
$ echo "1024 65535" | sudo tee /proc/sys/net/ipv4/ip_local_port_range
You can set all of these permanently by adding the following lines
vm.vdso_enabled = 0
vm.mmap_min_addr = 4096
net.ipv4.ip_local_port_range = 1024 65535
and running 'sysctl -p' as root.
WARNING: You should try setting these values by echoing them to the
given locations before adding them to sysctl.conf to see if they
cause any problems. For example, in some Ubuntu Gutsy installations,
it has been observed that changing the vdso settings will hang the system
and thus making permanent changes in sysctl.conf may, in these cases,
make your system unbootable.
2. INSTALLING MAEMO 4.1.2 SDK
The install script downloads the rootstraps for both ARMEL and i386
and sets up the targets inside Scratchbox. It also downloads the
Nokia EUSA licensed binary packages for you.
2.1 Running installer
You need to have Scratchbox Apophis r4 installed on your machine
before using the installer script.
To install the SDK, first download the script maemo-sdk-install_4.1.2.sh
from the location mentioned below:
After you have downloaded the script to your local machine, run the
script outside of the Scratchbox environment:
$ sh maemo-sdk-install_4.1.2.sh
Running the script starts the installation.
NOTE: If you have existing Scratchbox targets named DIABLO_ARMEL
or DIABLO_X86, you need to give the '-y' option for the script to
force reset of your targets:
$ sh maemo-sdk-install_4.1.2.sh -y
If your scratchbox is installed in a path alternative to
/scratchbox, then specify this alternative path using the '-s PATH'
You are presented with four options of installing SDK:
* 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
* Runtime Environment + All Dev and Dbg Packages. You will get a full
development environment plus debug symbols for many system components.
2.2 Installing Maemo 4.1.2 SDK manually
Generally, you do not need to do a manual install unless the maemo SDK
installer script cannot function in your specific environment. If you do,
then here is the way to do it.
Make sure that you have the latest Scratchbox Apophis r4 installation
prior to installing the SDK manually. See chapter 1.
Setting up the targets:
1. Login to scratchbox using the command below:
2. There are two ways to set up the targets, one using the command line
utility sb-conf and the other using the interactive sb-menu command.
In either case, the settings for the X86 and ARMEL targets are as
Devkits: perl debian-etch maemo3-tools cputransp
Devkits: perl debian-etch maemo3-tools
You can use the following command to set up the targets using the
$ sb-conf setup DIABLO_ARMEL -c cs2005q3.2-glibc2.5-arm -d perl:debian-etch:maemo3-tools:cputransp -t qemu-arm-0.8.2-sb2
$ sb-conf setup DIABLO_X86 -c cs2005q3.2-glibc2.5-i386 -d perl:debian-etch:maemo3-tools -t none
3. Download the minimal rootstraps for both architectures:
4. Install them on the respective targets using the command
5. Execute the command 'sb-conf install --etc --devkits --fakeroot'
in both the targets.
6. Execute the command 'apt-get update'
At this point, a simple C program should be compilable as the rootstrap
provides you with a minimal compilation environment.
The modular SDK provides you with the possibility to install only the
packages that you need. The repository contains meta-packages for different
components, for eg: desktop, connectivity, multimedia-framework etc.
We also have three top-level meta-packages that allow easy installation of
runtime, development and debug environments.
1. Maemo Runtime environment:
2. Maemo Runtime and development environment:
3. Maemo Runtime + development + debug environment:
Optionally, you can download the Nokia binaries by running the
Nokia binaries installer script outside scratchbox [ref: section 2.4].
2.3 Upgrading Diablo SDK from version 4.1.1 to 4.1.2
Diablo SDK can be easily upgraded from version 4.1.1 to 4.1.2.
The Nokia binaries for 4.1.2 SDK can be installed by running the Nokia
binaries installer script [ref: section 2.4].
2.4 Nokia EUSA licensed binaries
Some API's are provided as nokia-closed binaries. (Refer release notes
for the details) They are availble for the end user upon accepting the
EUSA (End User Software Agreement)license.
You can choose to download the Nokia binaries in the SDK installer.
However, if you are installing the SDK manually, you will need to download
the Nokia binaries installer separately from the following location:
Provide execute permission to the script
$ chmod +x maemo-sdk-nokia-binaries_4.1.2.sh
Run the script OUTSIDE scratchbox and follow the instructions
$ sh maemo-sdk-nokia-binaries_4.1.2.sh
Upon executing this script, the Nokia binaries are extracted into the folder
'maemo-sdk-nokia-binaries_4.1.2' under your scratchbox home directory.
If you want to install these, login to scratchbox (see commands
n section 2.2) and run the command:
'maemo-explicit' is a meta-package that will install all the provided
3. INSTALLING XEPHYR X11-SERVER
You need to install the Xephyr X11 server software to your computer
before you can run applications inside maemo 4.1.2 SDK.
Xephyr is an X11 server that provides a device screen for the
developer so that you can see all the maemo application windows and
visuals on your computer.
Xephyr is not included in the SDK, and should be installed to the
3.1 Getting Xephyr
Xephyr can for example be found at:
On Debian-based Linux distributions you can install Xephyr by doing
"apt-get install xserver-xephyr" outside scratchbox.
3.2 Xephyr startup parameters
Xephyr requires command line parameters so that it can provide a
real working window for the maemo environment.
Start Xephyr outside Scratchbox with the following parameters:
$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -extension Composite
In the Scratchbox environment the DISPLAY variable has to be set so
that it matches the display setting given above for the Xephyr
server (parameter :2 in the above example).
After the Xephyr server is running on the Linux host, you can start
the Hildon Application Framework with the following command:
This should start the Hildon Application Framework inside the Xephyr
Happy Hacking !