Documentation/Maemo 5 Final SDK Installation
Introduction
The following document describes the installation of the Maemo 5 Final SDK. Maemo SDK uses Scratchbox as the cross compilation environment into which Maemo specific development files are installed.
Before we begin with the installation, have a look at the minimum system requirements. We officially support x86-32 Debian based distributions, mainly Debian and Ubuntu though it is possible to install the SDK on other flavours of Linux too.
Once you are sure that your development machine fulfils these requirements, you can proceed with the following guidelines:
Maemo 5 SDK comes with two command line installation scripts and GUI installer (beta) to ease the SDK installation.
- Scratchbox installer script which downloads and installs the required version of Scratchbox onto your host machine.
- Maemo SDK installer which sets up two targets (armel and x86) inside Scratchbox, downloads the minimal rootstraps for both targets, and installs the open source development files based on the user selection during the installation process.
- GUI installer which combines both Scratchbox and SDK installation.
Maemo 5 SDK also provides the essential Nokia proprietary binary packages needed for Maemo development and additional Nokia applications in an authenticated repository. In order to have access to this repository, you will need to accept the End User License Agreement (EULA). For the complete functionality and usability of the Maemo SDK, it is required to install Nokia proprietary binary packages in addition to the open source packages.
What is not incuded in the Maemo SDK?
Xephyr X11 server software is needed on your host machine before you can run any applications in the Maemo SDK. It 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 host machine. This software is not included in the SDK mainly because it is available on most linux distributions. On Debian based linux systems, Xephyr can be installed outside Scratchbox environment using apt with root permission:
$ sudo apt-get install xserver-xephyr
On a Gentoo system you need to install xorg-server with the kdrive useflag. This builds the Xephyr binary.
Installing Maemo 5 SDK on x86-32 Debian based distribution
1. Download the scratchbox installer and the Maemo SDK installer scripts. These are the same scripts as are available through Forum Nokia: Maemo SDK at Forum Nokia.
$ wget http://repository.maemo.org/stable/5.0/maemo-scratchbox-install_5.0.sh http://repository.maemo.org/stable/5.0/maemo-sdk-install_5.0.sh
2. Set the permissions to execute the scripts.
$ chmod a+x ./maemo-scratchbox-install_5.0.sh ./maemo-sdk-install_5.0.sh
3. Run the scratchbox installer with root permission specifying the username to be added to scratchbox users group and sbox group. The username should be an existing user name from the host linux system. This will download about 420 MB of material from the web, which is not resumeable if interrupted.
$ sudo ./maemo-scratchbox-install_5.0.sh -u USER
4. The installation script adds the specified user to ‘sbox’ user group. For the group membership to be effective in the current terminal session, run the following command:
Note: This command will change the existing group ID during the current login session to ‘sbox’. If you do not want this change, just logout and log back in again for the group membership to be effective.
$ newgrp sbox
At this step, you should have a working Scratchbox environment ready.
5. Proceed further to run the Maemo SDK installer script. This script is run as 'user' outside the scratchbox environment.
$ ./maemo-sdk-install_5.0.sh
If you have installed Scratchbox in a path alternative to /scratchbox, you will need to specify the path with ‘-s PATH’ option. More information on available command line options can be found with --help option Follow the instructions on the go.
6. Once the script has successfully completed its execution, you can login into Scratchbox.
$ /scratchbox/login
If you are not able to login, take a look at the limitations of Scratchbox.
7. Proceed further to accept the EULA in order to obtain the Nokia proprietary binary packages. These Nokia binaries are essential for the complete functionality of the Maemo SDK.
7.1. Accept the EULA on this webpage
7.2. Copy the sources.list entry given to you after the license acceptance to your Scratchbox x86 and armel target’s /etc/apt/sources.list file. Execute the commands below on both targets.
[sbox-FREMANTLE_<target_name>: ~] > apt-get update [sbox-FREMANTLE_<target_name>: ~] > fakeroot apt-get install nokia-binaries nokia-apps
The above step installs all needed Nokia proprietary binary packages along with the open source binaries that have dependencies to Nokia proprietary binary packages. With this, your Maemo 5 SDK environment is set up completely and ready for development.
Starting/Shutting down the SDK UI
Before starting the UI framework, ensure that you have installed the following:
- Xephyr X11 server on the host machine outside the Scratchbox environment
- The SDK as described above
- The Nokia proprietary binary packages
1. Now, run Xephyr outside the scratchbox environment:
$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -kb &
2. Login to Scratchbox X86 target
$ /scratchbox/login Welcome to Scratchbox, the cross-compilation toolkit! Use 'sb-menu' to change your compilation target. See /scratchbox/doc/ for documentation. [sbox-FREMANTLE_X86: ~]>
3. Set the DISPLAY variable to match the display setting given for the Xephyr server.
[sbox-FREMANTLE_X86: ~] >export DISPLAY=:2
4. Start the UI framework .
[sbox-FREMANTLE_X86: ~] >af-sb-init.sh start
5. You will now see the UI framework up and running on the Xephyr window.
6. You can shut down the UI framework as follows:
[sbox-FREMANTLE_X86: ~] >af-sb-init.sh stop
Installation of x86-64 Debian based distributions
Since Scratchbox only supports x86-32 bit Linux host systems, we need to force the installation of x86-32 Scratchbox packages on the x86-64 bit machines. Using the -F option with the Scratchbox installation script can do this.
Installation procedure
- Download the Scratchbox installer and the Maemo SDK installer scripts.
$ wget http://repository.maemo.org/stable/5.0/maemo-scratchbox-install_5.0.sh http://repository.maemo.org/stable/5.0/maemo-sdk-install_5.0.sh
- Set permissions to execute the scripts.
$ chmod a+x ./maemo-scratchbox-install_5.0.sh ./maemo-sdk-install_5.0.sh
- Run the Scratchbox installer script as 'root user' with -F option, specifying the username to be added to Scratchbox users group sbox group as follows:
$ sudo ./maemo-scratchbox-install_5.0.sh -F -u USER
Upon successful installation of Scratchbox, continue to run the Maemo 5 Final SDK Installer as instructed in the x86-32 installation.
Starting Scratchbox on non-Debian based systems
If Scratchbox was installed from Debian packages, the /etc/init.d/scratchbox-core init script is installed and Scratchbox should start automatically when the system is rebooted. However, if you have installed Scratchbox from tarballs, then rebooting your machine will clear away all the mounts and binfmt_misc registrations that Scratchbox requires to work. To get your Scratchbox working again after reboot, you have to run the following command as root:
$ sudo /scratchbox/sbin/sbox_ctl start
Alternatively you can add sbox_ctl as an init script to the /etc/init.d directory and create the appropriate links at your system's runlevel directories. This procedure works on some systems:
$ ln -s /scratchbox/sbin/sbox_ctl /etc/init.d/scratchbox-core $ /usr/sbin/update-rc.d scratchbox-core defaults
Refer to your system's documentation for the correct instructions.
Upgrading from Maemo 5 Beta2 SDK
A smooth upgrade from beta2 to Final SDK is unfortunately not possible. Hence it is advised to freshly install the Final SDK. Before you do so, read through the instructions below.
Some of the Nokia applications shipped with the final SDK use a hard coded path for user home directory which presents a problem since the default username on the device differs from the username on the developer’s machine. To make these applications work, it is required to create a home directory that matches the hard coded value. This needs to be done outside scratchbox using root privileges. The -u option in the Scratchbox installer has been updated to create the necessary symlinks. Running the installer with -u option when the Scratchbox has been already installed will just add the user and create symlinks. Running it for already existing user will check for the symlink and create it if needed.
Run the command below to create the symlink for existing Scratchbox user:
$ sudo ./maemo-scratchbox-install_5.0.sh -u <EXISTING_USER>
Alternatively, you can create the symlinks manually as follows, if Scratchbox is installed in the default location:
$ sudo ln -s /scratchbox/users/<username>/home/<username> /scratchbox/users/<username>/home/user
The Final SDK installer additionally creates a directory /opt under /target/<target_name>/.
Reason: In order to facilitate installing applications under /opt on the device, a symlink /opt has been created pointing to /home/opt. The SDK inherits this feature. Under Scratchbox, /opt points to /target/links/opt which in turn points to /targets/<target_name>/opt. Installing the rootstraps makes this point to /home/opt, which is not what we want, since we need /opt to be target specific. In order to resolve this situation, we have to manually check whether /targets/<target_name>/opt is a symlink and if it is, remove it and create a directory with the same name.
Upgrading from Maemo 4.x/Diablo SDK
Due to the fact that there are API breaks in Fremantle, we cannot upgrade Diablo SDK to Fremantle. We can however have Fremantle Scratchbox targets co-exist with Diablo targets.
For this, we need to first upgrade the Scratchbox installation on our host machine.
- Download the Maemo5 scratchbox installer.
- Set executable permissions and run it as follows:
$ chmod a+x ./maemo-scratchbox-install_5.0.sh $ sudo ./maemo-scratchbox-install_5.0.sh -f -u <EXISTING_USER>
Once the Scratchbox installation is done, run the Maemo 5 Final SDK installer.
Manual Installation
On x86-32 Debian based systems:
- You can add the following line into your host machine's /etc/apt/sources.list file.
deb http://scratchbox.org/debian/ maemo5-sdk main
- Install the needed Scratchbox packages with root permission
$ sudo apt-get update $ sudo apt-get install scratchbox-core scratchbox-libs scratchbox-devkit-qemu scratchbox-devkit-debian scratchbox-devkit-doctools scratchbox-devkit-perl scratchbox-toolchain-host-gcc scratchbox-toolchain-cs2007q3-glibc2.5-arm7 scratchbox-toolchain-cs2007q3-glibc2.5-i486 scratchbox-devkit-svn scratchbox-devkit-git scratchbox-devkit-apt-https
On x86-64 Debian based systems:
- Download the Scratchbox packages from here.
- Force the installation of the x86-32 packages with root permission as follows:
$ sudo dpkg -i --force-architecture scratchbox-core scratchbox-libs scratchbox-devkit-qemu scratchbox-devkit-debian scratchbox-devkit-doctools scratchbox-devkit-perl scratchbox-toolchain-host-gcc scratchbox-toolchain-cs2007q3-glibc2.5-arm7 scratchbox-toolchain-cs2007q3-glibc2.5-i486 scratchbox-devkit-svn scratchbox-devkit-git scratchbox-devkit-apt-https
The Scratchbox packages will be unpacked to /scratchbox directory and the installation procedure will ask you some questions about the group and user accounts. Default group to Scratchbox is 'sbox'.
- Users who will be using Scratchbox should be added using the following command with root permission:
$ sudo /scratchbox/sbin/sbox_adduser USER yes
It will automatically include the user to the Scratchbox group, create user directories under /scratchbox/users and mount several directories (/dev, /proc, /tmp) under the user directory.
- Some of the Nokia applications shipped with the final SDK use a hard coded path for user home directory which presents a problem since the default username on the device differs from the username on the developer’s machine. To make these applications work, it is required to create a home directory that matches the hard coded value. This needs to be done outside scratchbox using root privileges.
$ sudo ln -s /scratchbox/users/<username>/home/<username> /scratchbox/users/<username>/home/user
- For the group membership to be effective in the current terminal session, run the following command:
$ newgrp sbox
Note: This command will change the existing group ID during the current login session to 'sbox'. If you do not want to change, simply logout and log back in for the group membership to be effective.
- Log-in to Scratchbox.
$ /scratchbox/login
- Configure the scratchbox x86 and armel targets as follows:
[sbox->:~]>sb-conf st FREMANTLE_X86 -c cs2007q3-glibc2.5-i486 -d perl:debian-etch:doctools:svn:git -t none
[sbox->:~]> sb-conf st FREMANTLE_ARMEL -c cs2007q3-glibc2.5-arm7 -d qemu:perl:debian-etch:doctools:svn:git -t qemu-arm-sb
- Download the minimal rootstraps.
[sbox->:~]> wget http://repository.maemo.org/stable/5.0/armel/maemo-sdk-rootstrap_5.0_armel.tgz http://repository.maemo.org/stable/5.0/i386/maemo-sdk-rootstrap_5.0_i386.tgz
- Switch to x86 target, install the devkits, etc and fakeroot into the target, install the minimal rootstrap and finally the Maemo development files.
[sbox->:~]> sb-conf se FREMANTLE_X86 [sbox-FREMANTLE_X86: ~] > sb-conf rs maemo-sdk-rootstrap_5.0_i386.tgz [sbox-FREMANTLE_X86: ~] > sb-conf in -edFL [sbox-FREMANTLE_X86: ~] > apt-get update [sbox-FREMANTLE_X86: ~] > fakeroot apt-get install maemo-sdk-debug
The meta-package 'maemo-sdk-debug' installs all needed open source runtime, development and debug pakcages into the target. Use maemo-sdk-runtime if you want only runtime packages to be installed or user maemo-sdk-dev if you want only the runtime + development packages to be installed.
- Accept the EULA from here to obtain the URL to access the Nokia binaries repository.
- Add the URL thus obtained to the Scratchbox target's /etc/apt/sources.list and do the following:
[sbox-FREMANTLE_X86: ~] >apt-get update [sbox-FREMANTLE_X86: ~] >fakeroot apt-get install nokia-binaries nokia-apps
- In order to facilitate installing applications under /opt on the device, a symlink /opt has been created pointing to /home/opt. The SDK inherits this feature. Under Scratchbox, /opt points to /target/links/opt which in turn points to /targets/<target_name>/opt. Installing the rootstraps makes this point to /home/opt, which is not what we want, since we need /opt to be target specific. In order to resolve this situation,
[sbox-FREMANTLE_X86: ~] >rm /targets/FREMANTLE_X86/opt [sbox-FREMANTLE_X86: ~] >mkdir /targets/FREMANTLE_X86/opt
- Execute similar steps on the armel target too to set it up:
[sbox-FREMANTLE_X86: ~]> sb-conf se FREMANTLE_ARMEL [sbox-FREMANTLE_ARMEL: ~] > sb-conf rs maemo-sdk-rootstrap_5.0_armel.tgz [sbox-FREMANTLE_ARMEL: ~] > sb-conf in -edFL [sbox-FREMANTLE_ARMEL: ~] > apt-get update [sbox-FREMANTLE_ARMEL: ~] > fakeroot apt-get install maemo-sdk-debug
- Add the same URL obtained above to access the Nokia binaries repository under /etc/apt/sources.list file of the Scratchbox armel target.
[sbox-FREMANTLE_ARMEL: ~] >apt-get update [sbox-FREMANTLE_ARMEL: ~] >fakeroot apt-get install nokia-binaries nokia-apps
- Create the /opt directory.
[sbox-FREMANTLE_ARMEL: ~] >rm /targets/FREMANTLE_ARMEL/opt [sbox-FREMANTLE_ARMEL: ~] >mkdir /targets/FREMANTLE_ARMEL/opt
With this, you must now have both the targets setup and ready to use.
Un-installation
Make sure that you have no process running inside Scratchbox. Uninstalling Scratchbox will remove everything that is installed and saved inside Scratchbox. Please take a backup of your files from Scratchbox user home directory if needed.
On Debian based systems, do the following with root permissions:
$ sudo apt-get remove scratchbox-* --purge $ sudo rm -rf /scratchbox
On non-Debian based systems, you need to stop scratchbox as follows before removing it.
$ sudo /scratchbox/sbin/sbox_ctl stop $ sudo rm -rf /scratchbox
Limitations of Scratchbox
The following limitations have been noted in the usage of Scratchbox:
VDSO support
Scratchbox does not work when VDSO32 support is enabled in the host's kernel. We're working on making it possible, but at the moment there are some workarounds, which are presented here.
If your host has VDSO32 turned on you will get an error like this when trying to login to Scratchbox.
No directory, logging in with HOME=/ Inconsistency detected by ld.so: rtld.c: 1192: dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed!
x86-64 kernel
x86-64 Linux kernels starting from version 2.6.25 enable VDSO32 by default. To temporarily disable VDSO32 execute
sysctl abi.vsyscall32=0
On Linux kernel 2.6.24 <= you can disable VDSO32 by executing
sysctl vm.vdso_enabled=0
or
sysctl kernel.vdso=0
The current setting of VDSO32 can be verified by using sysctl. Only values 0 and 2 are compatible with Scratchbox. In our examples we use 0 (disable). 2 enables compat mode.
You can set all of these permanently by adding the following lines to /etc/sysctl.conf
vm.vdso_enabled = 0 abi.vsyscall32 = 0 kernel.vdso = 0
Save the file and run the command:
$ sudo sysctl -p
Please note the correct line depends on your Linux kernel version. When you execute sysctl -p you may get a warning about unknown keys. You can safely ignore those warnings as long as one of the 3 settings works.
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.
Known Issues in the SDK
- Unnecessary warnings and debugging messages are printed out when the hildon application framework is started.
- Armel target does not bring up the UI framework
- It has been noted that Xephyr dies with the application framework at times. The crash in question might even be Xephyr related since the application framework behaves differently with different versions/builds of Xephyr. The case seems to be worst on Xephyr that comes with Ubuntu Jaunty, there Xephyr will die when running any application that contains an input field and clicking on that field with a mouse to invoke the input method. On Fedora Code 10 the Xephyr does not mind the mouse clicks but dies when shutting down the application framework. On the other hand Xephyr on Ubuntu Intrepid or even the Intrepid version recompiled for Jaunty does not experience crashing in these situations.
A patch is already available for the Xephyr on Ubuntu Jaunty and can be found at http://bugs.freedesktop.org/show_bug.cgi?id=21591.
- The performance of clutter can be improved by enabling hardware acceleration if not enabled already. In some cases, it would require installing restricted/proprietary drivers (Eg: on host machines with ATI or NVidia graphics card). Refer wiki [1] for more details.
- Running Xephyr with -kb option disables entry of “@” symbol. However, removing -kb option disables cursor keys.