Copyright (C) 2008 Nokia Corporation All rights reserved. RELEASE INFORMATION Project: maemo 4.0.1 Chinook Development Platform Version: 4.0.1 Baseline: OS2008 2.2007.51-3 Date: 2008-02-18 Updated: 2008-06-02 This INSTALL.txt file explains how to install and set up the maemo 4.0.1 development environment on your computer. This document is targeted for maemo developers. 1. UPDATING EXISTING SCRATCHBOX INSTALLATION ============================================ If you are currently using an older Scratchbox 0.9.X version you will need to upgrade to the latest Scratchbox Apophis r4. The recommended method is to remove old Scratchbox installation completely and to remove /scratchbox directory before installing the new version of Scratchbox. IMPORTANT: For maemo 2.1 users it is strongly recommended that you take a full backup of your Scratchbox development environment and related files before upgrading to the new version of Scratchbox. WARNING: Remember to stop scratchbox service before removing the scratchbox directory. This will unmount scratchbox bind mounts and thus prevent removing files from your host system. If you choose not to remove your old installation, refer to the following document for instructions on how to upgrade scratchbox. Upgrading is explained in Chapter 5.2 in the document "Installing Scratchbox" in the scratchbox.org website: http://scratchbox.org/documentation/user/scratchbox-1.0/html/installdoc.html 2. SCRATCHBOX APOPHIS R4 INSTALLATION ===================================== This chapter is for developers who do not have Scratchbox Apophis R4 installed on their computer yet. You can install Scratchbox in two ways: - using the installer script (recommended), or - manually It is strongly advised to use the Scratchbox installer script as explained in chapter 2.1. If for some reason you want to, or need to install Scratchbox manually jump to chapter 2.2. 2.1 Installing Scratchbox using the installer script This maemo release includes an installer script which will download and install the required version of scratchbox to your host computer. The installer script can be found from this URL: http://repository.maemo.org/stable/chinook/maemo-scratchbox-install_4.0.1.sh To install scratchbox, first download the script (from the same directory where you found this INSTALL.txt file) to your host computer and run the maemo-scratchbox-install_4.0.1.sh as user root: $ sudo chmod a+x ./maemo-scratchbox-install_4.0.1.sh $ sudo ./maemo-scratchbox-install_4.0.1.sh This is the easiest way to install scratchbox, and it is also the recommended way. Follow the instructions given by the script. Running the script will not modify any files outside its given install path. Downloaded files are temporarily stored in /tmp directory. These can be safely removed after the installer has completed. On Debian based distributions: the install script will use Debian packages. Packages install to the default path, /scratchbox. On any other Linux distribution: the install script will use .tar.gz files which can be installed to any given path. Scratchbox installation should be separate from host system's tools, e.g. to /scratchbox or /opt/scratchbox. Specify users to be added to scratchbox users with '-u USER' option. You will need to start a new login terminal after being added to the group for group membership to be effective. After the installer has finished you should have a working Scratchbox environment ready. In a rare situation, if the installer can not work properly on your system you may have to do a manual installation. This is explained in chapter 2.2 below. 2.2 Installing Scratchbox Apophis manually If you have installed Scratchbox with the script mentioned above in chapter 2.1 then you can skip this chapter. You need to install the following packages: scratchbox-core 1.0.8 scratchbox-libs 1.0.8 scratchbox-devkit-cputransp 1.0.3 scratchbox-devkit-debian 1.0.9 scratchbox-devkit-doctools 1.0.7 scratchbox-devkit-maemo3 1.0.1 scratchbox-devkit-perl 1.0.4 scratchbox-toolchain-cs2005q3.2-glibc2.5-arm 1.0.7.2 scratchbox-toolchain-cs2005q3.2-glibc2.5-i386 1.0.7 These packages can be downloaded from the scratchbox.org server. http://scratchbox.org/download/files/sbox-releases/apophis/ Detailed instructions on how to install Scratchbox to your computer are at: http://scratchbox.org/documentation/user/scratchbox-1.0/html/installdoc.html 2.3 Known limitation of scratchbox: Scratchbox doesn't work when VDSO support is enabled in the host's kernel. The status of VDSO support can be verified from the /proc filesystem. Only values 0 and 2 are compatible with scratchbox. Depending on the kernel version the VDSO support can most likely be found in /proc/sys/kernel/vdso or /proc/sys/vm/vdso_enabled. You can disable it for the current session by echoing a 0 to the given location under the /proc filesystem as root. For example on Ubuntu Hardy: $ echo 0 | sudo tee /proc/sys/vm/vdso_enabled The QEMU used by scratchbox is not compatible with mmap_min_addr value higher than 4096. This feature is not enabled in all kernels and the default value may differ. You can check the value of the mmap_min_addr from the /proc filesystem. The location for this setting is /proc/sys/vm/mmap_min_addr. You can set a desired value for the current session by echoing it to the given location as root. For Ubuntu Hardy: $ echo 4096 | sudo tee /proc/sys/vm/mmap_min_addr You can set both of these permanently by adding the following lines to /etc/sysctl.conf vm.vdso_enabled = 0 vm.mmap_min_addr = 4096 and running 'sysctl -p' as root. WARNING: You should try setting these values by echoing them to the given locations before adding them to sysctl.conf to see if they cause any problems. For example, in some Ubuntu Gutsy installations, it has been observed that changing the vdso settings will hang the system and thus making permanent changes in sysctl.conf may, in these cases, make your system unbootable. 3. INSTALLING MAEMO 4.0.1 SDK ============================= The install script downloads the rootstraps for both ARMEL and i386 and sets up the targets inside Scratchbox. It also downloads the Nokia EUSA licensed binary packages for you. 3.1 Running installer You need to have Scratchbox Apophis r4 installed on your machine before using the installer script. To install the SDK, first download the script from the same directory where you found this INSTALL.txt file. The name of the script is: maemo-sdk-install_4.0.1.sh After you have downloaded the script to your local machine, run the script outside of the Scratchbox environment: $ sh maemo-sdk-install_4.0.1.sh Running the script starts the installation. NOTE: If you have existing Scratchbox targets named CHINOOK_ARMEL or CHINOOK_X86, you need to give the '-y' option for the script to force reset of your targets: $ sh maemo-sdk-install_4.0.1.sh -y If your scratchbox is installed in a path alternative to /scratchbox, then specify this alternative path using the '-s PATH' option. You are presented with four options of installing SDK: * Minimal Rootstrap only. Choose this only if you are going to install all packages you need from repository. * Runtime Environment. Use this to install and run software inside Scratchbox. Cannot be used for building software. * Runtime Environment + All Dev Packages. Choose this to get a full development environment. * Runtime Environment + All Dev and Dbg Packages. You will get a full development environment plus debug symbols for many system components. 3.2 Installing Maemo 4.0.1 SDK manually Generally, you do not need to do a manual install unless the maemo SDK installer script cannot function in your specific environment. If you do, then here is the way to do it. Make sure that you have the latest Scratchbox Apophis r4 installation prior to installing the SDK manually. See chapters 1 and 2. Setting up the targets: ----------------------- 1. Login to scratchbox using the command below: $ scratchbox 2. There are 2 ways to set up the targets, one using the command line utility sb-conf and the other using the interactive sb-menu command. In either case, the settings for the X86 and ARMEL targets are as follows: ARMEL target: Compiler: cs2005q3.2-glibc2.5-arm Devkits: perl debian-etch maemo3-tools cputransp CPU-transparency: qemu-arm-0.8.2-sb2 X86 target: Compiler: cs2005q3.2-glibc2.5-i386 Devkits: perl debian-etch maemo3-tools CPU-transparency: none You can use the following command to set up the targets using the command line: ARMEL target: $ sb-conf setup CHINOOK_ARMEL -c cs2005q3.2-glibc2.5-arm -d perl:debian-etch:maemo3-tools:cputransp -t qemu-arm-0.8.2-sb2 X86 target: $ sb-conf setup CHINOOK_X86 -c cs2005q3.2-glibc2.5-i386 -d perl:debian-etch:maemo3-tools -t none 3. Download the minimal rootstraps for both architectures: wget http://repository.maemo.org/stable/chinook/armel/maemo-sdk-rootstrap_4.0.1_armel.tgz wget http://repository.maemo.org/stable/chinook/i386/maemo-sdk-rootstrap_4.0.1_i386.tgz 4. Install them on the respective targets using the command sb-conf rs 5. Execute the command 'sb-conf install --etc --devkits --fakeroot' in both the targets. 6. Execute the command 'apt-get update' At this point, a simple C program should be compilable as the rootstrap provides you with a minimal compilation environment. The modular SDK provides you with the possibility to install only the packages that you need. The repository contains meta-packages for different components, for eg: desktop, connectivity, multimedia-framework etc. We also have three top-level meta-packages that allow easy installation of runtime, development and debug environments. 1. Maemo Runtime environment: [sbox-CHINOOK_: ~] > fakeroot apt-get install maemo-sdk-runtime 2. Maemo Runtime and development environment: [sbox-CHINOOK_: ~] > fakeroot apt-get install maemo-sdk-dev 3. Maemo Runtime + development + debug environment: [sbox-CHINOOK_: ~] > fakeroot apt-get install maemo-sdk-debug Optionally, you can install the Nokia binaries by downloading and running the Nokia binaries installer script [ref: section 3.4]. 3.3 Upgrading from maemo 4.0 SDK Maemo 4.0 SDK can be easily upgraded to 4.0.1. Simply run the following commands on both i386 and armel targets. [sbox-CHINOOK_: ~] > apt-get update [sbox-CHINOOK_: ~] > fakeroot apt-get dist-upgrade The Nokia binaries for 4.0.1 SDK can be installed by running the Nokia binaries installer script [ref: section 3.4]. 3.4 Nokia EUSA licensed binaries Some of the Nokia binaries are avaiable under the End User Software License Agreement by running the Nokia binaries installer script. It can be fetched from http://repository.maemo.org/stable/chinook/maemo-sdk-nokia-binaries_4.0.1.sh Provide execute permission to the script $ > chmod +x maemo-sdk-nokia-binaries_4.0.1.sh Run the script outside scratchbox and follow the instructions $ > sh maemo-sdk-nokia-binaries_4.0.1.sh If you chose to accept the EUSA license then do this installation step. The package maemo-explicit is a metapackage of Nokia EUSA licensed binaries which can be installed to scratchbox targets. It is highly recommended to install this package on both targets to ensure a fully working system. If you want to install these, login to scratchbox (see commands above) and run the command: [sbox-CHINOOK_X86: ~] > fakeroot apt-get install maemo-explicit and for armel [sbox-CHINOOK_ARMEL ~] > fakeroot apt-get install maemo-explicit Now you have installed the Nokia EUSA binaries to your targets. 4. INSTALLING XEPHYR X11-SERVER =============================== You need to install the Xephyr X11 server software to your computer before you can run applications inside maemo 4.0 SDK. Xephyr is an X11 server that provides a device screen for the developer so that you can see all the maemo application windows and visuals on your computer. Xephyr is not included in the SDK, and should be installed to the host system. 4.1 Getting Xephyr Xephyr can for example be found at: http://packages.debian.org/unstable/x11/xserver-xephyr On Debian-based Linux distributions you can install Xephyr by doing "apt-get install xserver-xephyr" outside scratchbox. 4.2 Xephyr startup parameters Xephyr requires command line parameters so that it can provide a real working window for the maemo environment. Start Xephyr outside Scratchbox with the following parameters: $ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac -extension Composite In the Scratchbox environment the DISPLAY variable has to be set so that it matches the display setting given above for the Xephyr server (parameter :2 in the above example). [sbox-CHINOOK_X86:~] > export DISPLAY=:2 After the Xephyr server is running on the Linux host, you can start the Hildon Application Framework with the following command: [sbox-CHINOOK_X86:~] > af-sb-init.sh start This should start the Hildon Application Framework inside the Xephyr window. Happy Hacking ! --- END