Maemo 5 Beta 2 SDK Installation
Index
- Installing Maemo SDK on 32bit Debian based distribution
- Starting/ shutting down SDK UI
- Starting scratchbox
- Installing Maemo SDK on 64bit Debian based distribution
- Upgrading from Beta SDK
- Upgrading from Alpha SDK
- Upgrading from Diablo SDK
- Manual installation
- Uninstallation
- Limitations of Scratchbox
- Known issues in SDK
The following document describes the installation of the Maemo 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 32bit 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 steps:
1. Installing Maemo SDK on 32bit Debian based distribution
Maemo SDK comes with two installation scripts 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.
Maemo SDK also provides essential Nokia proprietary binary packages needed for Maemo development in an authenticated repository. In order to have access to this repository, you will need to accept the End User License Agreement (EULA).
For 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
Installation procedure
- Download the scratchbox installer and the Maemo SDK installer scripts.
$ wget http://repository.maemo.org/unstable/5.0beta2/maemo-scratchbox-install_5.0beta2.sh http://repository.maemo.org/unstable/5.0beta2/maemo-sdk-install_5.0beta2.sh
- Set the permissions to execute the scripts.
$ chmod a+x ./maemo-scratchbox-install_5.0beta2.sh
- Run the scratchbox installer with root permission specifying the username to be added to scratchbox users group and sbox group.
$ sudo ./maemo-scratchbox-install_5.0beta2.sh –u USER
- 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:
$ newgrp sbox
Note: This command will change the existing group ID during the current login session to ‘sbox’. If you do not want this change, simply logout and log in back again for the group membership to be effective.
- At this step, you should have a working scratchbox environment ready. Proceed further to run the Maemo SDK installer script. This script is run as 'user' outside the scratchbox environment.
$ sh maemo-sdk-install_5.0beta2.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 here.
- Follow the instructions on the go. Jump to here for detailed description of the execution of the Maemo SDK installer script.
- Once the script has successfully completed its execution, you can login into Scratchbox.
$ /scratchbox/login
If you are not able to login to Scratchbox, take a look at the limitations of Scratchbox.
- 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.
- Accept the EULA on this webpage
- 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_<X86/ARMEL>: ~] > apt-get update
[sbox-FREMANTLE_<X86/ARMEL>: ~] > fakeroot apt-get install nokia-binaries
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 SDK environment is set up completely and ready for development.
2. 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 Scratchbox environment
- The SDK as described above
- The Nokia proprietary binary packages
- Now, run Xephyr outside scratchbox environment:
$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -kb &
- Login to Scratchbox into the X86 target.
$ /scratchbox/login
[sbox->:~]> sb-conf se FREMANTLE_X86
- Set the DISPLAY variable to match the display setting given for the Xephyr server.
[sbox-FREMANTLE_X86: ~] > export DISPLAY=:2
- Start the UI framework .
[sbox-FREMANTLE_X86: ~] > af-sb-init.sh start
You will now see the UI framework up and running on the Xephyr window.
- Start the hildon-status-menu process to bring up the status area.
[sbox-FREMANTLE_X86: ~] > run-standalone.sh hildon-status-menu&
- You can shut down the UI framework as follows:
[sbox-FREMANTLE_X86: ~] > af-sb-init.sh stop
3. Starting Scratchbox
If Scratchbox was installed from Debian or RPM packages, the /etc/init.d/scratchbox-core init script is installed and Scratchbox should start automatically when the system is rebooted. However, if you 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:
$ /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.
4. Installing on 64bit Debian based distrubution
Since Scratchbox supports Linux host system with 32 architecture only, we need to force the installation of 32bit Scratchbox packages on the 64 bit machines. This can be done by using the -F option with the scratchbox installation script. Also,the 64 bit Linux kernels starting from version 2.6.25 enable VDSO by default which is not supported by Scratchbox. You can workaround this by adding 'vdso32=0' as a kernel boot parameter.
Alternatively, you can edit the /boot/grub/menu.lst file as follows with root permissions:
- Go to the Default kernel options section. At the end of the line that reads # kopt=root=.........., add vdso32=0.
For example, on Ubuntu 64 bit Jaunty release:
# kopt=root=UUID=f28af361-b724-4ee8-b840-760870e04032 ro vdso32=0
- Run the following command with root permission to update grub:
$ update-grub
This will ensure that the kernel boot parameter is retained permanently.
- Reboot your machine for the changes too take effect.
- Download the Scratchbox installer and the Maemo SDK installer scripts.
$ wget http://repository.maemo.org/unstable/5.0beta2/maemo-scratchbox-install_5.0beta2.sh http://repository.maemo.org/unstable/5.0beta2/maemo-sdk-install_5.0beta2.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:
$ ./maemo-scratchbox-install_5.0beta2.sh –u USER -F
The rest of the instructions are same as that for 32bit installation. Refer here to continue.
5. Upgrading from Beta SDK
- Four scratchbox packages have been updated since the beta SDK release. You can upgrade them as follows:
- Debian based 32bit systems:
$ sudo apt-get update
$ sudo apt-get install scratchbox-devkit-doctools scratchbox-toolchain-cs2007q3-glibc2.5-arm7 scratchbox-toolchain-cs2007q3-glibc2.5-i486 scratchbox-devkit-apt-https
-
- On Debian based 64bit systems:
- Download the Scratchbox packages from here.
- Force the installation of the 32bit packages with root permission as follows:
- On Debian based 64bit systems:
$ sudo dpkg -i --force-architecture scratchbox-devkit-doctools scratchbox-toolchain-cs2007q3-glibc2.5-arm7 scratchbox-toolchain-cs2007q3-glibc2.5-i486 scratchbox-devkit-apt-https
- Once the scratchbox packages are upgraded, it is recommended to reinstall the SDK as described in section 1. Unfortunately, a smooth upgrade using 'apt-get dist-upgrade' from beta SDK release is not possible. Nevertheless, if one wants to try an upgrade, here are the steps to follow on both the targets:
[sbox->:~FREMANTLE_<X86/ARMEL>]>apt-get update
[sbox->:~FREMANTLE_<X86/ARMEL>]>fakeroot apt-get -f install pulseaudio-module-extra evolution-data-server-addressbook-dbg (May need multiple attempts)
[sbox->:~FREMANTLE_<X86/ARMEL>]>fakeroot apt-get dist-upgrade
6. Upgrading from Alpha SDK
- Since the scratchbox packages have been upgraded in the beta release, we need to first upgrade them on our host machine. Once the scratchbox packages are upgraded, please reinstall the SDK as described in section 1 (smooth upgrade using 'apt-get dist-upgrade' from alpha SDK release is not possible)
Scratchbox upgrade
- Debian based 32bit systems:
$ 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 Debian based 64bit systems:
- Download the Scratchbox packages from here.
- Force the installation of the 32bit 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
This will ensure that the latest scratchbox packages are installed including the new qemu devkit.
- In order to utilize the new qemu devkit, we need to reconfigure the existing scratchbox targets as follows:
[sbox->:~FREMANTLE_X86]> sb-conf st -f FREMANTLE_X86 -c cs2007q3-glibc2.5-i486 -d perl:debian-etch:doctools:svn:git -t none
[sbox->:~FREMANTLE_X86]> sb-conf st -f FREMANTLE_ARMEL -c cs2007q3-glibc2.5-arm7 -d qemu:perl:debian-etch:doctools:svn:git -t qemu-arm-sb
7. Upgrading from 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. On debian based systems:
- Update the URL in the /etc/apt/sources.list.d/maemo4.0_scratchbox.list file to point to the maemo5 scratchbox repository.
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
- Once the scratchbox installation is done, run the Fremantle Beta SDK installer to install the beta SDK.
8. Manual installation
It is generally not recommended to perform a manual installation of the SDK unless otherwise there occurs a problem with the automated installation. In any case, here are the instructions to follow:
Fremantle Beta SDK requires the following Scratchbox packages:
On 32bit 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 64bit Debian based systems:
- Download the Scratchbox packages from here.
- Force the installation of the 32bit 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:
$ /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.
- 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:apt-https -t none
[sbox->:~]> sb-conf st FREMANTLE_ARMEL -c cs2007q3-glibc2.5-arm7 -d qemu:perl:debian-etch:doctools:svn:git:apt-https -t qemu-arm-sb
- Download the minimal rootstraps.
[sbox->:~]> wget http://repository.maemo.org/unstable/5.0beta2/armel/maemo-sdk-rootstrap_5.0beta2_armel.tgz http://repository.maemo.org/unstable/5.0beta2/i386/maemo-sdk-rootstrap_5.0beta2_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.0beta2_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
- Execute siimilar 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.0beta2_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
With this, you must now have both the targets setup and ready to use.
Read section 2 on how to start the UI framework.
9. Uninstalling Maemo SDK
Make sure that you have no preocess 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:
$ /scratchbox/sbin/sbox_ctl stop
$ apt-get remove scratchbox-* --purge
$ rm -rf /scratchbox
Maemo SDK installer script execution
Step 1:
On running the Maemo SDK installation script, the Open source License Agreement is displayed. Acceptance of the licence is needed inorder to proceed with the installation. Press 'Enter' key to accept and proceed.
Step 2:
You are presented with four options to configure the installation of the SDK:
- Minimal Rootstrap only: Choose this only if you want to install only a minimal environment. Note that you will then need to manually install the packages you need.
- Runtime Environment: Use this to install and run software inside Scratchbox. For development, we recommend option 3.
- 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.
The default selection is option 3. Make your selection and proceed further.
Step 3:
The summary of the selection made uptil now is presented to you. If all settings are as you have expected, proceed further. Else, cancel the installation and start again.
The installer continues to download the minimal rootstraps for both X86 and ARMEL targets, installs them and there after installs the packages based on your selection in step 2. Once the installation is successfull, you have the open source software installed inside the Scratchbox targets.
Back to Installation procedure
Options available for the Maemo SDK installer
The sdk installer can be run with various options if needed. The available options are:
-v Display version and exit
-h Show this usage guide
-c Use exisitng downloads, don't try to download again
-y Yes, force remove of existing targets
-d Use defaults. Non-interactive mode
-p URI Specify http_proxy for Scratchbox user (By default, host system's proxy is used ).
-s PATH Specify Scratchbox installation path (default /scratchbox)
-q NAME Specify Qemu version (default qemu-arm-cvs-m)
-a FILE Specify alternative sources.list file for both targets
-A Advanced mode
10. Limitations of Scratchbox
The following limitations have been noted in the usage of Scratchbox:
1. VDSO support
Scratchbox does not work when VDSO 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 VDSO 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!
64 bit kernel version 2.6.25 or newer
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. It has been reported that with a kernel boot parameter it is possible to disable VDSO http://bugs.maemo.org/show_bug.cgi?id=3479 .
The kernel boot parameter option has been verified to work on a 64 bit system. In short;
add vdso32=0 to your kernel boot parameters
Older kernel versions
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 Intrepid:
$ sudo sysctl vm.vdso_enabled=0
2. Tip: /etc/sysctl.conf
You can set all of these permanently by adding the following lines to /etc/sysctl.conf . The vdso_enabled option is not available in latest 64 bit kernels.
- Open the file in an editor, for example nano
$ sudo nano /etc/sysctl.conf
- Add the following line to the file:
vm.vdso_enabled = 0
- Exit and save the file by pressing ctrl+x. Then run:
$ sudo sysctl -p
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.
10. Known issues in SDK
The following issues have been noted during the testing of the SDK:
1. In armel target, the hildon UI does not come up while starting the hildon application framework. This is mainly due drawbacks in the user mode qemu.
2. Task switcher is not present. Hence you can run one application at a time from the UI. The final Maemo 5 will contain however the task switcher.
3. The SDK is not currently usable with only open components mainly due to come open to closed dependencies. This makes installation of Nokia closed binaries crucial for the complete functionality of the SDK.
4. On launching Application Manager, "Operation failed" banner appears and one cannot save any newly added catalogues. This can be solved by installing fakeroot-net package from the SDK repository which provides fakeroot command to the application. However, the catalogues fail to refresh completely. This problem is being investigated internally.
5.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 NVedia graphics card). Refer wiki for more details
6. Unnecessary warnings and debugging messages are printed out when the hildon application framework is started.
7. 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 had 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.