Documentation/Maemo 5 Final SDK Installation

(Upgrading from Maemo 5 Beta2 SDK)
(On x86 and x86_64 Debian-based systems)
 
(155 intermediate revisions not shown)
Line 1: Line 1:
-
=Introduction=
+
'''WARNING: Never rm -r /scratchbox or subfolders, you got bindmounts of proc/ dev/ etc to your REAL SYSTEM. You will kill your system when indiscriminately deleting stuff in /scratchbox!'''
 +
 
 +
==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.
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 32bit Debian based distributions, mainly Debian and Ubuntu though it is possible to install the SDK on other flavours of Linux too.
+
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:
+
Once you are sure that your development machine fulfills 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.
+
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.
+
* 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 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.
+
* 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.
+
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?==
+
===What is not included 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
+
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.
 +
If you choose to install Maemo SDK using the GUI installer on Debian based systems, it will provide an option to install Xephyr for you.
-
=Installing Maemo 5 SDK on 32bit Debian based distribution=
+
If not, you can manually install Xephyr as follows:
-
1. Download the scratchbox installer and the Maemo SDK installer scripts.
+
On Debian based linux systems, Xephyr can be installed outside Scratchbox environment using apt with root permission:
-
  $ 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
+
  $ 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.
-
2. Set the permissions to execute the scripts.
+
==Installing Maemo 5 SDK using GUI Installer==
 +
{{ambox
 +
|type=warning
 +
|text=recent requests on IRC suggest this wizard GUI installer is completely broken and thus SHOULD NOT be used. Follow text based installation scheme instead, as this GUI thing will fail out after downloading 1GB and you have to start all over again}}
-
$ chmod a+x ./maemo-scratchbox-install_5.0.sh  ./ maemo-sdk-install_5.0.sh
 
 +
Maemo 5 SDK installation is now made easy with GUI installer. This
 +
installer will install Scratchbox and Maemo 5 SDK on Debian based
 +
systems. This installer will allow installation of nokia closed packages and
 +
applications provided that EULA at [http://tablets-dev.nokia.com/eula/index.php this webpage] is accepted.
-
3. Run the scratchbox installer with root permission specifying the username to be added to scratchbox users group and sbox group.
+
===Features of the GUI installer===
-
$ sudo ./maemo-scratchbox-install_5.0.sh –u USER
+
* Install/Upgrade Scratchbox
 +
* Installation of Maemo 5 SDK
 +
* Installation of nokia-binaries
 +
* Installation of nokia-apps
 +
* Installation of Xephyr, if missing
 +
* Can create a launcher for Xephyr on Desktop
 +
* Can create a shortcut to Scratchbox home folder on Desktop
 +
* Can create Maemo 5 info page on Desktop that contains useful links for developers
 +
* Uninstallation of Scratchbox and targets (Debian-based distros only)
 +
GUI installer offers standard and custom installation modes in a wizard. Standard installation will use default settings, while custom offers more choices. Please note that standard mode will overwrite any of the standard targets (<code>FREMANTLE_X86</code>, <code>FREMANTLE_ARMEL</code>) if present, but contents of Scratchbox home will be preserved. Please use the custom mode if you don't want to overwrite your targets.
-
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:
+
The GUI installer Qt application requires Python bindings for Qt. GUI installer can install the required packages if not already installed.
-
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.
+
The installer will use the <code>http_proxy</code> environment variable if available. If your connection does not seem to work, you will be asked to manually enter proxy settings.
-
$ newgrp sbox
+
GUI installer has been tested on Ubuntu Karmic and Debian Lenny, both 32bit and 64bit versions. The GUI installer needs to download Maemo SDK so it requires a working Internet connection. On 64bit kernel, you need to disable VDSO for 32bit applications manually.
-
At this step, you should have a working Scratchbox environment ready.
+
On systems with Grub2, this can be done in the file /etc/default/grub.
 +
===Starting installation with GUI installer===
-
5. Proceed further to run the Maemo SDK installer script. This script is run as 'user' outside the scratchbox environment.
+
There are some missing options in this Python script, and if you run from non-Debian based Linux systems you will errors, because it will not automatically define the installation path of Scratchbox, to correct this error you must patch this script.
-
$ ./maemo-sdk-install_5.0.sh
+
Also you must uncheck the Xephyr checkbox and install it manually.
 +
<source lang="diff">
 +
  129c129
 +
  < SB_PATH = "/scratchbox"
 +
  ---
 +
  > SB_PATH = "/opt/scratchbox"
 +
  2297a2298
 +
  >      opt = opt + "-s /opt/scratchbox"
 +
  2351a2353
 +
  >      cmd = cmd +" -s /opt/scratchbox"
 +
</source>
-
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
+
wget http://repository.maemo.org/stable/5.0/maemo-sdk-install-wizard_5.0.py
-
Follow the instructions on the go.
+
chmod a+x maemo-sdk-install-wizard_5.0.py
 +
$ Installer requires root privileges
 +
  Ubuntu
 +
    sudo ./maemo-sdk-install-wizard_5.0.py
 +
  Debian
 +
    su -c ./maemo-sdk-install-wizard_5.0.py
-
6. Once the script has successfully completed its execution, you can login into Scratchbox.
+
===Limitations of the GUI installer===
-
$ /scratchbox/login
+
* As the installer will do package installation, you should quit all package managers before running it.
 +
* Please note that detecting Scratchbox is not perfect and it will detect only if it is installed in the <code>/scratchbox</code> path.
 +
* Please note that python-qt features used in this installer might not be available in older Ubuntu and Debian distros.
 +
* Due to differences in versions of Python Qt bindings, certain parts of installation can work differently on different systems.
 +
* Installer only shows required settings on 64-bit machines but does not add them automatically.
 +
* Installer will always use DISPLAY :2, if you want to use a different value, you need to change it manually.
 +
* GUI installer does not work on SUSE Linux. You can use command line installers instead.
-
If you are not able to login, take a look at the [[#Limitations of Scratchbox|limitations of Scratchbox]].
+
==Installing Maemo 5 SDK using Text-based Installer==
 +
===Installing Maemo 5 SDK on 32-/64-bit Debian/Ubuntu-based distributions===
 +
Since the Scratchbox site has packages for both architectures, and the Debian packages work fine on Ubuntu, it is easiest to just install from the Hathor release.
 +
1. Set up a new APT source using the instructions at http://www.scratchbox.org/download/scratchbox-hathor/
-
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.
+
2. Follow the installation instructions at http://www.scratchbox.org/documentation/user/scratchbox-1.0/html/installdoc.html or follow on for simplified instructions.
-
7.1. Accept the EULA on [http://tablets-dev.nokia.com/eula/index.php this webpage] <br>
+
3. Update your APT cache:
-
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.
+
<code>
 +
$ sudo apt-get update
 +
</code>
 +
then install Scratchbox:
 +
<code>
 +
$ sudo apt-get install scratchbox-core scratchbox-devkit-apt-https scratchbox-devkit-autotools-legacy scratchbox-devkit-debian-squeeze scratchbox-devkit-doctools scratchbox-devkit-git scratchbox-devkit-perl scratchbox-devkit-python-legacy scratchbox-devkit-qemu scratchbox-devkit-svn scratchbox-libs scratchbox-toolchain-cs2007q3-glibc2.5-arm7 scratchbox-toolchain-cs2007q3-glibc2.5-i486 scratchbox-toolchain-host-gcc
 +
</code>
 +
The installation will ask you some questions about users and groups to set up.
-
[sbox-FREMANTLE_<target_name>: ~] > apt-get update
+
4. Download the SDK setup script:
-
[sbox-FREMANTLE_<target_name>: ~] > fakeroot apt-get install nokia-binaries nokia-apps
+
<code>
 +
$ wget http://repository.maemo.org/stable/5.0/maemo-sdk-install_5.0.sh
 +
</code>
-
The above step installs all needed Nokia proprietary binary packages along with the open source binaries that have dependencies to Nokia proprietary binary packages.
+
5. Since Scratchbox Hathor is based on Debian Squeeze, and the SDK script assumes etch is to be used, we need to make a small change to it:
-
With this, your Maemo 5 SDK environment is set up completely and ready for development.
+
<code>
 +
$ sed -i -e 's/etch/squeeze/g' maemo-sdk-install_5.0.sh
 +
</code>
-
=Starting/Shutting down the SDK UI=
+
6. Set the permissions to execute the script:
 +
<code>
 +
$ chmod +x maemo-sdk-install_5.0.sh
 +
</code>
-
Before starting the UI framework, ensure that you have installed the following:
+
7. Users of Ubuntu 10.04 LTS will need to do the following to fix the installation, note that this may reduce system security! [http://talk.maemo.org/showpost.php?p=636394&postcount=8]
-
*Xephyr X11 server on the host machine outside the Scratchbox environment
+
<code>
-
*The SDK as described above
+
$ echo "vm.mmap_min_addr = 0" | sudo tee -a /etc/sysctl.conf
-
*The Nokia proprietary binary packages
+
$ sudo sysctl -p
 +
</code>
-
1. Now, run Xephyr outside the scratchbox environment:
+
8. If you have not already added a user to scratchbox, do so now:
 +
<code>
 +
$ sudo /scratchbox/sbin/sbox_adduser <username>
 +
</code>
-
$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac –kb &
+
At this step, you should have a working Scratchbox environment ready.
 +
9. Proceed further to run the Maemo SDK installer script. This script is run as <code><user></code> outside the Scratchbox environment.
 +
<code>
 +
$ ./maemo-sdk-install_5.0.sh
 +
</code>
-
2. Login to Scratchbox X86 target
+
10. If you are installing running this script in Ubuntu 10.10 Maverick Meerkat, you might find the following error:
 +
<code>Error opening terminal: xterm</code>
 +
In that case follow the instructions at http://www.terabyteunlimited.com/kb/article.php?id=454
 +
 
 +
11. If you have installed Scratchbox in a path alternative to <code>/scratchbox</code>, 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.
 +
11. Once the script has successfully completed its execution, you can login into Scratchbox.
 +
<code>
  $ /scratchbox/login
  $ /scratchbox/login
-
+
</code>
-
Welcome to Scratchbox, the cross-compilation toolkit!
+
If you are not able to login, take a look at the [[#Limitations of Scratchbox|limitations of Scratchbox]].
-
+
-
Use 'sb-menu' to change your compilation target.
+
-
+
-
See /scratchbox/doc/ for documentation.
+
-
+
-
[sbox-FREMANTLE_X86: ~]>
+
 +
12. 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:
-
3. Set the DISPLAY variable to match the display setting given for the Xephyr server.
+
12.1. Accept the EULA on [http://tablets-dev.nokia.com/eula/index.php this webpage] <br/>
 +
12.2. Copy the <code>sources.list</code> entry given to you after the license acceptance to your Scratchbox x86 and armel target’s <code>/etc/apt/sources.list</code> file.  
-
[sbox-FREMANTLE_X86: ~] >export DISPLAY=:2
+
'''EDIT:''' You can now just use the following <code>sources.list</code> entry:
 +
deb http://repository.maemo.org/ fremantle/4bc37c7c77ebe90177c050b805a8dc79 nokia-binaries
 +
Execute the commands below on the <code>FREMANTLE_ARMEL</code> and <code>FREMANTLE_X86</code> targets.
-
4. Start the UI framework .
+
[sbox-FREMANTLE_X86: ~] > sb-conf select FREMANTLE_ARMEL
 +
[sbox-FREMANTLE_ARMEL: ~] > nano /etc/apt/sources.list  # add deb line
 +
[sbox-FREMANTLE_ARMEL: ~] > apt-get update
 +
[sbox-FREMANTLE_ARMEL: ~] > fakeroot apt-get install nokia-binaries nokia-apps
-
  [sbox-FREMANTLE_X86: ~] >af-sb-init.sh start
+
  [sbox-FREMANTLE_ARMEL: ~] > sb-conf select FREMANTLE_X86
 +
[sbox-FREMANTLE_X86: ~] > nano /etc/apt/sources.list  # add deb line
 +
[sbox-FREMANTLE_X86: ~] > apt-get update
 +
[sbox-FREMANTLE_X86: ~] > 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.
-
5. You will now see the UI framework up and running on the Xephyr window.
+
13. If you got any DNS errors with <code>apt-get install</code> resolving 'repository.maemo.org', you have need to update the resolver config inside scratchbox with <code>sudo /scratchbox/sbin/sbox_sync</code>
-
6. You can shut down the UI framework as follows:
+
===Installing Maemo 5 SDK on openSUSE===
-
  [sbox-FREMANTLE_X86: ~] >af-sb-init.sh stop
+
There are instructions <del>at [http://en.opensuse.org/Maemo5 opensuse.org].</del>
 +
At the moment, the instructions are only available at the old version of the openSUSE-wiki: [http://old-en.opensuse.org/Maemo5 http://old-en.opensuse.org/Maemo5]
 +
==Installing Maemo 5 SDK on non-Linux operating systems==
-
=Installation of 64bit Debian based distributions=
+
If you do not have a Linux environment (Windows or Mac OS X), you can install a [[Documentation/Maemo_5_Developer_Guide/Development_Environment/Maemo_SDK_Virtual_Images|Maemo SDK virtual machine image]]
-
Since Scratchbox  only supports 32 bit Linux host systems, we need to force the installation of 32bit Scratchbox packages on the 64 bit machines. Using the -F option with the Scratchbox installation script can do this.
+
from [http://tablets-dev.nokia.com/maemo-dev-env-downloads.php tablets-dev.nokia.com]. [http://www.vmware.com/products/player/ VMPlayer is required].
-
==64bit kernel, version >= 2.6.25==
+
==Starting/Shutting down the SDK UI==
-
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:
+
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
-
*Go to the Default kernel options section. At the end of the line that reads
+
1. Now, run Xephyr outside the scratchbox environment:
-
  # kopt=root=.........., add vdso32=0.
+
  $ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac &
 +
Ubuntu 10.04 users using the package in the repositories will have to run the same command without the <code>-host-cursor</code> and <code>-kb</code>, however the terminal window will have to stay open.
 +
For recent Ubuntu releases the recommended Xephyr command line (using Finnish keyboard layout) is:
-
For example, on Ubuntu 64 bit Jaunty release:
+
$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -keybd ephyr,,,xkbmodel=evdev,xkblayout=fi
-
# kopt=root=UUID=f28af361-b724-4ee8-b840-760870e04032 ro vdso32=0
+
Ubuntu 10.10:
 +
$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac
-
*Run the following command with root permission to update grub:
+
Ubuntu 10.10 & poulsbo (GMA 500, Nokia Booklet 3G):
-
  $ sudo update-grub
+
  $ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -nodri
-
This will ensure that the kernel boot parameter is retained permanently.
+
To run <code>Maemo5 SDK</code> from desktop edit <code>/usr/local/bin/start_xephyr.sh</code>
-
*Reboot your machine for the changes too take effect.
+
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: ~]>
-
==Grub2==
+
3. Set the DISPLAY variable to match the display setting given for the Xephyr server.
-
*If your system uses grub2, you will have to edit the file /etc/default/grub.
+
-
For example, on Ubuntu 9.10 using grub2, you can edit this file by adding vdso32=0 to the line that starts with GRUB_CMDLINE_LINUX_DEFAULT. By default, it is similar to the following:
+
-
  GRUB_CMDLINE_LINUX_DEFAULT=”quiet splash”
+
  [sbox-FREMANTLE_X86: ~] >export DISPLAY=:2
-
And after the addition:
+
4. Start the UI framework .
-
  GRUB_CMDLINE_LINUX_DEFAULT=”quiet splash vdso32=0”
+
  [sbox-FREMANTLE_X86: ~] >af-sb-init.sh start
-
*Regenerate the grub file by running the following command with root permission:
+
5. You will now see the UI framework up and running on the Xephyr window.
-
$ sudo update-grub
+
6. You can shut down the UI framework as follows:
 +
  [sbox-FREMANTLE_X86: ~] >af-sb-init.sh stop
-
*Reboot your machine for the changes too take effect.
+
==Starting Scratchbox on non-Debian based systems==
-
 
+
If Scratchbox was installed from Debian packages, the <code>/etc/init.d/scratchbox-core</code> 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:
-
==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 32bit 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
  $ 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:
+
Alternatively you can add <code>sbox_ctl</code> as an init script to the <code>/etc/init.d</code> 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
  $ ln -s /scratchbox/sbin/sbox_ctl /etc/init.d/scratchbox-core
  $ /usr/sbin/update-rc.d scratchbox-core defaults
  $ /usr/sbin/update-rc.d scratchbox-core defaults
-
 
Refer to your system's documentation for the correct instructions.
Refer to your system's documentation for the correct instructions.
 +
==Upgrading from Maemo 5 Beta2 SDK==
-
=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.
-
A smooth upgrade from beta2 to Final SDK is unfortunately not possible. Hence it is advised to freshly 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.
-
 
+
-
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:
Run the command below to create the symlink for existing Scratchbox user:
-
  $ sudo ./maemo-scratchbox-install_5.0.sh –u <EXISTING_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:
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
+
  $ sudo ln -s /scratchbox/users/<username>/home/<username> /scratchbox/users/<username>/home/user
 +
The Final SDK installer additionally creates a directory <code>/opt</code> under <code>/target/<target_name>/</code>.
-
The Final SDK installer additionally creates a directory /opt under /target/<target_name>/.
+
'''Reason:''' In order to facilitate installing applications under <code>/opt</code> on the device, a symlink <code>/opt</code> has been created pointing to <code>/home/opt</code>. The SDK inherits this feature. Under Scratchbox, <code>/opt</code> points to <code>/target/links/opt</code> which in turn points to <code>/targets/<target_name>/opt</code>. Installing the rootstraps makes this point to <code>/home/opt</code>, which is not what we want, since we need <code>/opt</code> to be target specific.  In order to resolve this situation, we have to manually check whether <code>/targets/<target_name>/opt</code> is a symlink and if it is, remove it and create a directory with the same 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==
-
=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.
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.
Line 223: Line 294:
  $ chmod a+x ./maemo-scratchbox-install_5.0.sh
  $ chmod a+x ./maemo-scratchbox-install_5.0.sh
-
  $ sudo  ./maemo-scratchbox-install_5.0.sh –f –u <EXISTING_USER>
+
  $ sudo  ./maemo-scratchbox-install_5.0.sh -U -u <EXISTING_USER> -s /scratchbox
-
 
+
Once the Scratchbox installation is done, run the Maemo 5 Final SDK installer.
Once the Scratchbox installation is done, run the Maemo 5 Final SDK installer.
 +
==Manual Installation==
-
=Manual Installation=
+
===On x86 and x86_64 Debian-based systems===
-
 
+
-
'''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
+
* You can add the following line into your host machine's <code>/etc/apt/sources.list</code> file.
 +
deb http://scratchbox.org/debian/ hathor main
-
*Install the needed Scratchbox packages with root permission
+
* Install the needed Scratchbox packages with root permission
  $ sudo apt-get update
  $ 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
  $ 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
 +
The Scratchbox packages will be unpacked to <code>/scratchbox</code> directory and the installation procedure will ask you some questions about the group and user accounts. Default group to Scratchbox is 'sbox'.
-
'''On 64bit Debian based systems:'''
+
* Users who will be using Scratchbox should be added using the following command with root permission:
-
 
+
-
*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:
+
  $ sudo /scratchbox/sbin/sbox_adduser USER yes
  $ sudo /scratchbox/sbin/sbox_adduser USER yes
 +
It will automatically include the user to the Scratchbox group, create user directories under <code>/scratchbox/users</code> and mount several directories (<code>/dev</code>, <code>/proc</code>, <code>/tmp</code>) under the user directory.
-
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.
-
*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
-
$ 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:
-
 
+
-
 
+
-
*For the group membership to be effective in the current terminal session, run the following command:
+
  $ newgrp sbox
  $ newgrp sbox
Line 273: Line 329:
'''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.
'''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.
-
*Log-in to Scratchbox.
+
  $ /scratchbox/login
  $ /scratchbox/login
 +
* Configure the scratchbox x86 and armel targets as follows:
-
*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
-
[sbox->:~]>sb-conf st FREMANTLE_X86 –c cs2007q3-glibc2.5-i486 -d perl:debian-etch:doctools:svn:git -t none
+
* Download the minimal rootstraps.
-
[sbox->:~]> sb-conf st FREMANTLE_ARMEL -c cs2007q3-glibc2.5-arm7 -d qemu:perl:debian-etch:doctools:svn:git -t qemu-arm-sb
+
 +
[sbox->:~]> wget http://repository.maemo.org/stable/fremantle/armel/maemo-sdk-rootstrap_5.0_20.2010.36-2_armel.tgz http://repository.maemo.org/stable/fremantle/i386/maemo-sdk-rootstrap_5.0_20.2010.36-2_i386.tgz
-
*Download the minimal rootstraps.
+
* Switch to x86 target, install the devkits, etc and fakeroot into the target, install the minimal rootstrap and finally the Maemo development files.
-
  [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
+
  [sbox->:~]> sb-conf se FREMANTLE_X86
 +
[sbox-FREMANTLE_X86: ~] > sb-conf rs maemo-sdk-rootstrap_5.0_20.2010.36-2_i386.tgz
 +
* Some users seem to have problems downloading all files with apt http pipelining enabled. If you want to make sure or you get download errors like "104 connection reset by peer" at the fakeroot steps below, then disable http pipelining with the next command:
 +
[sbox-FREMANTLE_X86: ~] > echo 'Acquire::http::Pipeline-Depth "0";' >> /etc/apt/apt.conf.d/00maemo
-
*Switch to x86 target, install the devkits, etc and fakeroot into the target, install the minimal rootstrap and finally the Maemo development files.
+
* either way, continue here:
-
 
+
-
[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: ~] > sb-conf in -edFL
  [sbox-FREMANTLE_X86: ~] > apt-get update
  [sbox-FREMANTLE_X86: ~] > apt-get update
  [sbox-FREMANTLE_X86: ~] > fakeroot apt-get install maemo-sdk-debug
  [sbox-FREMANTLE_X86: ~] > fakeroot apt-get install maemo-sdk-debug
 +
The meta-package <code>maemo-sdk-debug</code> installs all needed open source runtime, development and debug pakcages into the target. Use <code>maemo-sdk-runtime</code> if you want only runtime packages to be installed or use <code>maemo-sdk-dev</code> if you want only the runtime and development packages to be installed.
 +
 +
* Accept the EULA from [http://tablets-dev.nokia.com/eula/index.php here]  to obtain the URL to access the Nokia binaries repository. (OBSOLETE)
 +
 +
* Instead add repository:
-
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.
+
deb http://repository.maemo.org/ fremantle/<token_number_here> nokia-binaries
-
*Accept the EULA from here  to obtain the URL to access the Nokia binaries repository.
+
* For token check the post:
 +
http://talk.maemo.org/showthread.php?p=1399082#post1399082)
-
*Add the URL thus obtained to the Scratchbox target's /etc/apt/sources.list and do the following:
+
 
 +
* Add the URL thus obtained to the Scratchbox target's <code>/etc/apt/sources.list</code> and do the following:
  [sbox-FREMANTLE_X86: ~] >apt-get update
  [sbox-FREMANTLE_X86: ~] >apt-get update
  [sbox-FREMANTLE_X86: ~] >fakeroot apt-get install nokia-binaries nokia-apps
  [sbox-FREMANTLE_X86: ~] >fakeroot apt-get install nokia-binaries nokia-apps
 +
* In order to facilitate installing applications under <code>/opt on the device, a symlink <code>/opt</code> has been created pointing to <code>/home/opt</code>. The SDK inherits this feature. Under Scratchbox, <code>/opt</code> points to <code>/target/links/opt</code> which in turn points to <code>/targets/<target_name>/opt</code>. Installing the rootstraps makes this point to <code>/home/opt</code>, which is not what we want, since we need <code>/opt,/code> to be target specific. In order to resolve this situation,
-
*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 -rf /targets/FREMANTLE_X86/opt
-
 
+
-
  [sbox-FREMANTLE_X86: ~] >rm /targets/FREMANTLE_X86/opt
+
  [sbox-FREMANTLE_X86: ~] >mkdir /targets/FREMANTLE_X86/opt
  [sbox-FREMANTLE_X86: ~] >mkdir /targets/FREMANTLE_X86/opt
 +
* Execute similar steps on the armel target too to set it up:
-
*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_20.2010.36-2_armel.tgz
 +
* again,the next command disables http pipelining, if you like:
 +
[sbox-FREMANTLE_X86: ~] > echo 'Acquire::http::Pipeline-Depth "0";' >> /etc/apt/apt.conf.d/00maemo
-
[sbox-FREMANTLE_X86: ~]> sb-conf se FREMANTLE_XARMEL
+
* pipelining disabled or not, here we go again...
-
[sbox-FREMANTLE_ARMEL: ~] > sb-conf rs maemo-sdk-rootstrap_5.0_armel.tgz
+
  [sbox-FREMANTLE_ARMEL: ~] > sb-conf in -edFL
  [sbox-FREMANTLE_ARMEL: ~] > sb-conf in -edFL
  [sbox-FREMANTLE_ARMEL: ~] > apt-get update
  [sbox-FREMANTLE_ARMEL: ~] > apt-get update
  [sbox-FREMANTLE_ARMEL: ~] > fakeroot apt-get install maemo-sdk-debug
  [sbox-FREMANTLE_ARMEL: ~] > fakeroot apt-get install maemo-sdk-debug
-
 
+
* Add the same URL obtained above to access the Nokia binaries repository under <code>/etc/apt/sources.list</code> file of the Scratchbox armel target.
-
*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: ~] >apt-get update
  [sbox-FREMANTLE_ARMEL: ~] >fakeroot apt-get install nokia-binaries nokia-apps
  [sbox-FREMANTLE_ARMEL: ~] >fakeroot apt-get install nokia-binaries nokia-apps
 +
* Create the <code>/opt</code> directory.
-
*Create the /opt directory.
+
  [sbox-FREMANTLE_ARMEL: ~] >rm -rf /targets/FREMANTLE_ARMEL/opt
-
 
+
-
  [sbox-FREMANTLE_ARMEL: ~] >rm /targets/FREMANTLE_ARMEL/opt
+
  [sbox-FREMANTLE_ARMEL: ~] >mkdir /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.
With this, you must now have both the targets setup and ready to use.
Line 340: Line 403:
[[#Starting/Shutting down the SDK UI|Start the UI framework]].
[[#Starting/Shutting down the SDK UI|Start the UI framework]].
-
=Un-installation=
+
==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.
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.
Line 348: Line 411:
  $ sudo apt-get remove scratchbox-* --purge
  $ sudo apt-get remove scratchbox-* --purge
  $ sudo rm -rf /scratchbox
  $ sudo rm -rf /scratchbox
-
 
On non-Debian based systems, you need to stop scratchbox as follows before removing it.
On non-Debian based systems, you need to stop scratchbox as follows before removing it.
Line 355: Line 417:
  $ sudo rm -rf /scratchbox
  $ sudo rm -rf /scratchbox
 +
'''not stopping scratchbox will keep the bindmounts and you'll nuke /proc /dev etc of your *real* system with the second line above!'''
-
 
+
==Limitations of Scratchbox==
-
=Limitations of Scratchbox=
+
The following limitations have been noted in the usage of Scratchbox:
The following limitations have been noted in the usage of Scratchbox:
-
==VDSO support==
+
===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.
+
Scratchbox versions [http://lists.scratchbox.org/pipermail/scratchbox-users/2010-June/001618.html prior to 1.0.18 (Hathor)] do not work when VDSO32 support is enabled in the host's kernel, although there are some workarounds for older versions, 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=/
  No directory, logging in with HOME=/
Line 370: Line 433:
  ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed!
  ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed!
 +
===x86-64 kernel===
-
==64 bit kernel version 2.6.25 or newer==
+
x86-64 Linux kernels starting from version 2.6.25 enable VDSO32 by default. To temporarily disable VDSO32 execute
-
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.
+
-
The kernel boot parameter option has been verified to work on a 64 bit system. In short;
+
sysctl abi.vsyscall32=0
-
add vdso32=0 to your kernel boot parameters
+
On Linux kernel 2.6.24 <= you can disable VDSO32 by executing
-
==Older kernel versions==
+
sysctl vm.vdso_enabled=0
-
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.
+
or
-
For example, on Ubuntu Jaunty:
+
sysctl kernel.vdso=0
-
$ sudo sysctl vm.vdso_enabled=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 <code>/etc/sysctl.conf</code>
-
==Tip: /etc/sysctl.conf==
+
vm.vdso_enabled = 0
-
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.
+
abi.vsyscall32 = 0
-
 
+
  kernel.vdso = 0
-
Open the file in an editor, for example nano and add the following line:
+
-
 
+
-
  vm.vdso_enabled = 0  
+
Save the file and run the command:
Save the file and run the command:
Line 399: Line 459:
  $ sudo sysctl -p
  $ 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.
+
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 <code>sysctl.conf</code> 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 <code>sysctl.conf</code> may, in these cases, make your system unbootable.
 +
==Known Issues in the SDK==
-
=Known Issues in the SDK=
+
* A list of issues and their solutions can be found in the [[Developer_FAQ#Maemo_SDK_and_Scratchbox|Developer FAQ]] article
-
*Unnecessary warnings and debugging messages are printed out when the hildon application framework is started.
+
* 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 Core 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.<br/>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. Binaries packages for [http://launchpadlibrarian.net/30330126/xserver-xephyr_1.6.3-1ubuntu2_i386.deb xserver-xephyr] package and its dependencies ([http://launchpadlibrarian.net/27533744/libgpg-error0_1.6-1ubuntu1_i386.deb libgpg-error0] and [http://launchpadlibrarian.net/28623981/libgcrypt11_1.4.4-2ubuntu2_i386.deb libcrypt11]) can be download from Ubuntu Jaunty repositories.
 +
* 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 to [[Maemo 5 Clutter performance]] for more details.
 +
* Running Xephyr with <code>-kb</code> option disables entry of “@” symbol. However, removing <code>-kb</code> option disables cursor keys.
 +
* Running Xephyr with <code>-host-cursor</code> is causing Xephyr to crash in Ubuntu Lucid and Debian Squeeze when the Hildon Application Framework is closed.
 +
* Xephyr in Ubuntu Lucid does not support the <code>-kb</code> option anymore. https://bugs.launchpad.net/ubuntu/+source/xorg-server/+bug/531872
 +
* In order to run ARMEL binaries in scratchbox the <code>mmap_min_address</code> needs to be set to 4096 or lower. Normally the SDK installer warns about that, but in Ubuntu Lucid the /proc entry is visible only to root, so the SDK installer can not see it. https://bugs.launchpad.net/ubuntu/+source/linux/+bug/568844 This also [http://lists.scratchbox.org/pipermail/scratchbox-users/2010-June/001624.html prevents qemu from checking the value], in which case it is assumed to be 0. Because of this, until the bug is fixed (kernel 2.6.34 is unaffected, and at least that version will be in Maverick), the value should be set to 0 on Lucid.
 +
** [http://talk.maemo.org/showpost.php?p=636394&postcount=8 To install on Ubuntu 10.04] (restart installation afterwards):
 +
$ sudo su
 +
$ echo "vm.mmap_min_addr = 0" >> /etc/sysctl.conf
 +
$ sysctl -p
 +
$ exit #to go back to user
-
*Armel target does not bring up the UI framework
+
== Next steps ==
-
*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.
+
Once you have Scratchbox installed and the Maemo 5 UI running in Xephyr, you have everything you need to start building, packaging and developing software for the N900.
-
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.
+
To get started with a sample application, try following this tutorial on [[packaging]].
-
*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 [http://wiki.maemo.org/Maemo5_clutter_performance] for more details.
 
-
*Running Xephyr with –kb option disables entry of “@” symbol. However, removing –kb option disables cursor keys.
+
[[Category:Scratchbox]]

Latest revision as of 19:41, 18 May 2014

WARNING: Never rm -r /scratchbox or subfolders, you got bindmounts of proc/ dev/ etc to your REAL SYSTEM. You will kill your system when indiscriminately deleting stuff in /scratchbox!

Contents

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 fulfills 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 included 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.

If you choose to install Maemo SDK using the GUI installer on Debian based systems, it will provide an option to install Xephyr for you.

If not, you can manually install Xephyr as follows:

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 using GUI Installer

Image:Ambox_notice.png
recent requests on IRC suggest this wizard GUI installer is completely broken and thus SHOULD NOT be used. Follow text based installation scheme instead, as this GUI thing will fail out after downloading 1GB and you have to start all over again


Maemo 5 SDK installation is now made easy with GUI installer. This installer will install Scratchbox and Maemo 5 SDK on Debian based systems. This installer will allow installation of nokia closed packages and applications provided that EULA at this webpage is accepted.

Features of the GUI installer

  • Install/Upgrade Scratchbox
  • Installation of Maemo 5 SDK
  • Installation of nokia-binaries
  • Installation of nokia-apps
  • Installation of Xephyr, if missing
  • Can create a launcher for Xephyr on Desktop
  • Can create a shortcut to Scratchbox home folder on Desktop
  • Can create Maemo 5 info page on Desktop that contains useful links for developers
  • Uninstallation of Scratchbox and targets (Debian-based distros only)

GUI installer offers standard and custom installation modes in a wizard. Standard installation will use default settings, while custom offers more choices. Please note that standard mode will overwrite any of the standard targets (FREMANTLE_X86, FREMANTLE_ARMEL) if present, but contents of Scratchbox home will be preserved. Please use the custom mode if you don't want to overwrite your targets.

The GUI installer Qt application requires Python bindings for Qt. GUI installer can install the required packages if not already installed.

The installer will use the http_proxy environment variable if available. If your connection does not seem to work, you will be asked to manually enter proxy settings.

GUI installer has been tested on Ubuntu Karmic and Debian Lenny, both 32bit and 64bit versions. The GUI installer needs to download Maemo SDK so it requires a working Internet connection. On 64bit kernel, you need to disable VDSO for 32bit applications manually.

On systems with Grub2, this can be done in the file /etc/default/grub.

Starting installation with GUI installer

There are some missing options in this Python script, and if you run from non-Debian based Linux systems you will errors, because it will not automatically define the installation path of Scratchbox, to correct this error you must patch this script.

Also you must uncheck the Xephyr checkbox and install it manually.

  129c129
  < SB_PATH = "/scratchbox"
  ---
  > SB_PATH = "/opt/scratchbox"
  2297a2298
  >       opt = opt + "-s /opt/scratchbox"
  2351a2353
  >       cmd = cmd +" -s /opt/scratchbox"
wget http://repository.maemo.org/stable/5.0/maemo-sdk-install-wizard_5.0.py
chmod a+x maemo-sdk-install-wizard_5.0.py
$ Installer requires root privileges
  Ubuntu
   sudo ./maemo-sdk-install-wizard_5.0.py
  Debian
   su -c ./maemo-sdk-install-wizard_5.0.py

Limitations of the GUI installer

  • As the installer will do package installation, you should quit all package managers before running it.
  • Please note that detecting Scratchbox is not perfect and it will detect only if it is installed in the /scratchbox path.
  • Please note that python-qt features used in this installer might not be available in older Ubuntu and Debian distros.
  • Due to differences in versions of Python Qt bindings, certain parts of installation can work differently on different systems.
  • Installer only shows required settings on 64-bit machines but does not add them automatically.
  • Installer will always use DISPLAY :2, if you want to use a different value, you need to change it manually.
  • GUI installer does not work on SUSE Linux. You can use command line installers instead.

Installing Maemo 5 SDK using Text-based Installer

Installing Maemo 5 SDK on 32-/64-bit Debian/Ubuntu-based distributions

Since the Scratchbox site has packages for both architectures, and the Debian packages work fine on Ubuntu, it is easiest to just install from the Hathor release.

1. Set up a new APT source using the instructions at http://www.scratchbox.org/download/scratchbox-hathor/

2. Follow the installation instructions at http://www.scratchbox.org/documentation/user/scratchbox-1.0/html/installdoc.html or follow on for simplified instructions.

3. Update your APT cache:

$ sudo apt-get update

then install Scratchbox:

$ sudo apt-get install scratchbox-core scratchbox-devkit-apt-https scratchbox-devkit-autotools-legacy scratchbox-devkit-debian-squeeze scratchbox-devkit-doctools scratchbox-devkit-git scratchbox-devkit-perl scratchbox-devkit-python-legacy scratchbox-devkit-qemu scratchbox-devkit-svn scratchbox-libs scratchbox-toolchain-cs2007q3-glibc2.5-arm7 scratchbox-toolchain-cs2007q3-glibc2.5-i486 scratchbox-toolchain-host-gcc

The installation will ask you some questions about users and groups to set up.

4. Download the SDK setup script:

$ wget http://repository.maemo.org/stable/5.0/maemo-sdk-install_5.0.sh

5. Since Scratchbox Hathor is based on Debian Squeeze, and the SDK script assumes etch is to be used, we need to make a small change to it:

$ sed -i -e 's/etch/squeeze/g' maemo-sdk-install_5.0.sh

6. Set the permissions to execute the script:

$ chmod +x maemo-sdk-install_5.0.sh

7. Users of Ubuntu 10.04 LTS will need to do the following to fix the installation, note that this may reduce system security! [1]

$ echo "vm.mmap_min_addr = 0" | sudo tee -a /etc/sysctl.conf
$ sudo sysctl -p

8. If you have not already added a user to scratchbox, do so now:

$ sudo /scratchbox/sbin/sbox_adduser <username>

At this step, you should have a working Scratchbox environment ready.

9. 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

10. If you are installing running this script in Ubuntu 10.10 Maverick Meerkat, you might find the following error: Error opening terminal: xterm In that case follow the instructions at http://www.terabyteunlimited.com/kb/article.php?id=454

11. 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.

11. 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.

12. 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:

12.1. Accept the EULA on this webpage
12.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.

EDIT: You can now just use the following sources.list entry:

deb http://repository.maemo.org/ fremantle/4bc37c7c77ebe90177c050b805a8dc79 nokia-binaries

Execute the commands below on the FREMANTLE_ARMEL and FREMANTLE_X86 targets.

[sbox-FREMANTLE_X86: ~] > sb-conf select FREMANTLE_ARMEL
[sbox-FREMANTLE_ARMEL: ~] > nano /etc/apt/sources.list  # add deb line 
[sbox-FREMANTLE_ARMEL: ~] > apt-get update
[sbox-FREMANTLE_ARMEL: ~] > fakeroot apt-get install nokia-binaries nokia-apps
[sbox-FREMANTLE_ARMEL: ~] > sb-conf select FREMANTLE_X86
[sbox-FREMANTLE_X86: ~] > nano /etc/apt/sources.list  # add deb line 
[sbox-FREMANTLE_X86: ~] > apt-get update
[sbox-FREMANTLE_X86: ~] > 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.

13. If you got any DNS errors with apt-get install resolving 'repository.maemo.org', you have need to update the resolver config inside scratchbox with sudo /scratchbox/sbin/sbox_sync

Installing Maemo 5 SDK on openSUSE

There are instructions at opensuse.org.

At the moment, the instructions are only available at the old version of the openSUSE-wiki: http://old-en.opensuse.org/Maemo5

Installing Maemo 5 SDK on non-Linux operating systems

If you do not have a Linux environment (Windows or Mac OS X), you can install a Maemo SDK virtual machine image from tablets-dev.nokia.com. VMPlayer is required.

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 &

Ubuntu 10.04 users using the package in the repositories will have to run the same command without the -host-cursor and -kb, however the terminal window will have to stay open. For recent Ubuntu releases the recommended Xephyr command line (using Finnish keyboard layout) is:

$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -keybd ephyr,,,xkbmodel=evdev,xkblayout=fi

Ubuntu 10.10:

$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac

Ubuntu 10.10 & poulsbo (GMA 500, Nokia Booklet 3G):

$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -nodri

To run Maemo5 SDK from desktop edit /usr/local/bin/start_xephyr.sh


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

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 -U -u <EXISTING_USER> -s /scratchbox

Once the Scratchbox installation is done, run the Maemo 5 Final SDK installer.

Manual Installation

On x86 and x86_64 Debian-based systems

  • You can add the following line into your host machine's /etc/apt/sources.list file.
deb http://scratchbox.org/debian/ hathor 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

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/fremantle/armel/maemo-sdk-rootstrap_5.0_20.2010.36-2_armel.tgz http://repository.maemo.org/stable/fremantle/i386/maemo-sdk-rootstrap_5.0_20.2010.36-2_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_20.2010.36-2_i386.tgz
  • Some users seem to have problems downloading all files with apt http pipelining enabled. If you want to make sure or you get download errors like "104 connection reset by peer" at the fakeroot steps below, then disable http pipelining with the next command:
[sbox-FREMANTLE_X86: ~] > echo 'Acquire::http::Pipeline-Depth "0";' >> /etc/apt/apt.conf.d/00maemo
  • either way, continue here:
[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 use maemo-sdk-dev if you want only the runtime and development packages to be installed.

  • Accept the EULA from here to obtain the URL to access the Nokia binaries repository. (OBSOLETE)
  • Instead add repository:

deb http://repository.maemo.org/ fremantle/<token_number_here> nokia-binaries

  • For token check the post:

http://talk.maemo.org/showthread.php?p=1399082#post1399082)


  • 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 <code>/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,/code> to be target specific. In order to resolve this situation,
[sbox-FREMANTLE_X86: ~] >rm -rf /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_20.2010.36-2_armel.tgz
  • again,the next command disables http pipelining, if you like:
[sbox-FREMANTLE_X86: ~] > echo 'Acquire::http::Pipeline-Depth "0";' >> /etc/apt/apt.conf.d/00maemo
  • pipelining disabled or not, here we go again...
[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 <code>/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 -rf /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.

Start the UI framework.

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

not stopping scratchbox will keep the bindmounts and you'll nuke /proc /dev etc of your *real* system with the second line above!

Limitations of Scratchbox

The following limitations have been noted in the usage of Scratchbox:

VDSO support

Scratchbox versions prior to 1.0.18 (Hathor) do not work when VDSO32 support is enabled in the host's kernel, although there are some workarounds for older versions, 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

  • A list of issues and their solutions can be found in the Developer FAQ article
  • 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 Core 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. Binaries packages for xserver-xephyr package and its dependencies (libgpg-error0 and libcrypt11) can be download from Ubuntu Jaunty repositories.
  • 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 to Maemo 5 Clutter performance for more details.
  • Running Xephyr with -kb option disables entry of “@” symbol. However, removing -kb option disables cursor keys.
  • Running Xephyr with -host-cursor is causing Xephyr to crash in Ubuntu Lucid and Debian Squeeze when the Hildon Application Framework is closed.
  • Xephyr in Ubuntu Lucid does not support the -kb option anymore. https://bugs.launchpad.net/ubuntu/+source/xorg-server/+bug/531872
  • In order to run ARMEL binaries in scratchbox the mmap_min_address needs to be set to 4096 or lower. Normally the SDK installer warns about that, but in Ubuntu Lucid the /proc entry is visible only to root, so the SDK installer can not see it. https://bugs.launchpad.net/ubuntu/+source/linux/+bug/568844 This also prevents qemu from checking the value, in which case it is assumed to be 0. Because of this, until the bug is fixed (kernel 2.6.34 is unaffected, and at least that version will be in Maverick), the value should be set to 0 on Lucid.
$ sudo su
$ echo "vm.mmap_min_addr = 0" >> /etc/sysctl.conf
$ sysctl -p
$ exit #to go back to user

Next steps

Once you have Scratchbox installed and the Maemo 5 UI running in Xephyr, you have everything you need to start building, packaging and developing software for the N900.

To get started with a sample application, try following this tutorial on packaging.