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