Copyright (C) 2007 Nokia Corporation All rights reserved. RELEASE INFORMATION Project: maemo 3.0 'bora' Development Platform Version: 3.0 Baseline: Week 51-6 of product SW (2.2006.51-6) Date: 2007-01-26 This INSTALL.txt file explains how to install and setup the maemo 3.0 development environment in your computer. This document is targeted for maemo developers. Content: 1. Updating existing Scratchbox installation 2. Scratchbox Apophis r4 installation 2.1 Installing Scratchbox using the new installer script 2.2 Installing Scratchbox Apophis manually 3. Installing maemo 'bora' 3.0 SDK 3.1 Installing maemo 3.0 with installer script 3.2 Installing maemo 3.0 manually 3.2.1 Running the Nokia Binaries installer 3.2.2 Setting up the ARMEL target inside Scratchbox 3.2.3 Setting up the X86 target inside Scratchbox 3.2.4 Install Scratchbox provided virtual packages 3.3 Nokia EUSA licensed binaries 3.4 Completing the installation 4. Installing Xephyr X11 server 4.1 Getting Xephyr 4.2 Xephyr startup parameters 5. How to flash the developer rootfs 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 Scratchbox. Note that, with this release you cannot upgrade the maemo 2.1 SDK targets to maemo 3.0 level. 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 new Scratchbox. WARNING: Remember to stop scratchbox service before removing 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 how to upgrade the 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 (=SB) Apophis R4 installed in their computer yet. You can install SB Apophis two ways: - 2.1) using the new SB installer script (recommended) - 2.2) installing SB manually It is strongly advised to use the new SB installer script as explained in chapter 2.1 below. If for some reason you want to or you need to install SB manually jump to chapter 2.2. 2.1 Installing Scratchbox using the new installer script This maemo release includes installer script which will download and install the required version of scratchbox on your host computer. Installer script can now be found from this path: http://repository.maemo.org/stable/bora/maemo-scratchbox-install_3.0.sh To install scratchbox first download the script (from the same directory where you found this INSTALL.txt file) to your host computer and just run the maemo-scratchbox-install_3.0.sh as user root: $ sudo chmod a+x ./maemo-scratchbox-install_3.0.sh $ sudo ./maemo-scratchbox-install_3.0.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 it's given install path. Downloaded files are temporarily stored in /tmp directory. These can be safely removed after the install has taken place. On Debian-based distributions: the install will use per default Debian .deb packages. Packages install to default path /scratchbox . On any other Linux distribution: the install 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 your Linux PC. In a rare situation, if the installer can not work properly in your host Linux system you may have to do a manual installation. This is explained in the chapter 2.2 below. 2.2 Installing Scratchbox Apophis manually If you have installed Scratchbox with the script mentioned in the above chapter 2.1 then you can skip this chapter. You need to install the following packages: scratchbox-core 1.0.7 scratchbox-libs 1.0.7 scratchbox-devkit-cputransp 1.0.1 scratchbox-devkit-debian 1.0.6 scratchbox-devkit-doctools 1.0.5 scratchbox-devkit-perl 1.0.4 scratchbox-toolchain-cs2005q3.2-glibc-arm 1.0.5 scratchbox-toolchain-cs2005q3.2-glibc-i386 1.0.5 These packages can be downloaded from the scratchbox.org server. http://scratchbox.org/download/files/sbox-releases/apophis/ Detailed instructions how to install Scratchbox in you computer are: http://scratchbox.org/documentation/user/scratchbox-1.0/html/installdoc.html 3. INSTALLING MAEMO 3.0 'bora' SDK ================================== With this release you can use the new maemo-sdk-install_3.0.sh installer script that installs the maemo 3.0 SDK to your local machine. Using the installer script is the preferred way to install maemo 3.0 'bora' release and we recommend using the installer script over a manual installation. 3.1 Installing maemo 3.0 with installer script This script downloads the rootstraps for both ARMEL and i386 and setups the targets inside the Scratchbox. It also downloads the Nokia EUSA licensed binary packages for you. You need to have the Scratchbox Apophis r4 readily installed in 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) to your host. The name of the script is: maemo-sdk-install_3.0.sh After you have downloaded the script to your local machine just run the maemo-sdk-install_3.0.sh outside the scratchbox environment: $ bash maemo-sdk-install_3.0.sh Running the script starts the installation. NOTE: If you have existing scratchbox targets named SDK_ARMEL or SDK_X86, you need to give the '-y' option for the script to force reset of your targets, like this: $ bash maemo-sdk-install_3.0.sh -y If your scratchbox is installed in a path alternative to /scratchbox, then specify this alternative path using '-s PATH' option. You can also install the maemo 3.0 SDK manually. For more details, please follow the instructions below. You can now jump to chapter 3.3 if the automatic installation was succesful. 3.2 Installing maemo 3.0 manually This chapter explains the manual installation process of maemo 3.0 'bora' sdk. In a normal situation you do not need to do a manual installation but instead use the provided maemo installer script (see chapter 3.1 for details). Manual installation is needed only if for some reason the maemo installer script can not function properly in your spesific Linux environment. Start the manual installation by first copying the rootstraps and installer files to your development machine. Get the rootstrap files for i386 and armel architectures, and optionally the Nokia binaries installer: Go to: http://repository.maemo.org/stable/bora/ and download the following files: armel/maemo-sdk-rootstrap_3.0_armel.tgz i386/maemo-sdk-rootstrap_3.0_i386.tgz maemo-sdk-nokia-binaries_3.0.sh After you have installed (or upgraded) Scratchbox copy these rootstrap files to the directory "/scratchbox/packages" in your development Linux machine. 3.2.1 Running the Nokia binaries installer ! This step is part of manual installation. The maemo installer ! script will take care of this step for you. Some Nokia proprietary packages are only made available as binaries. To make these packages available, you need to run the installer and accept the displayed license. Accepting the license will extract the files to a directory under your Scratchbox home path. $ bash maemo-sdk-nokia-binaries_3.0.sh Nokia binaries repository will be extracted to a directory under your scratchbox home path. After the binaries are succesfully installed, the script will display instructions on how the repository can be added to scratchbox targets' /etc/apt/sources.list files. 3.2.2 Setting up the ARMEL target inside Scratchbox ! This step is part of manual installation. The maemo installer ! script will take care of this step for you. After you have finished the step above start the scratchbox environment by running the command below in your Linux machine: $ scratchbox Welcome to Scratchbox, the cross-compilation toolkit! ... There is two ways how you can setup a compilation target. You can use the sb-conf command or you can use the new sb-menu command. This example uses the sb-conf command. The settings for ARMEL target are: Compiler: cs2005q3.2-glibc-arm Devkits: perl, doctools, debian, cputransp CPU transparency: qemu-arm-0.8.1-sb2 Note: The target name can be chosen freely. This example uses SDK_ARMEL. Run the following sb-conf commands inside scratchbox: [sbox-: ~/ ] > sb-conf setup SDK_ARMEL --compiler=cs2005q3.2-glibc-arm \ --devkits=perl:debian:doctools:cputransp \ --cputransp=qemu-arm-0.8.1-sb2 [sbox-: ~/ ] > sb-conf select SDK_ARMEL Shell restarting... [sbox-SDK_ARMEL: ~/ ] > sb-conf rootstrap /scratchbox/packages/maemo-sdk-rootstrap_3.0_armel.tgz Unpacking rootstrap... [sbox-SDK_ARMEL: ~/ ] > sb-conf install --etc --devkits --fakeroot Installing fakeroot version 1.4.2... Your ARMEL target is now ready for use. ! IMPORTANT: Do NOT install the ARMEL C-library files from Scratchbox ! toolchains. Do NOT select the C-library in sb-menu or use the ! options -c or --clibrary with "sb-conf install" command. ! ! If you accidently chose to install armel C-libraries from Scratchbox ! you can reset the problem by running a command: ! ! [sbox-SDK_ARMEL: ~/ ] > sb-reinstall /scratchbox/packages/maemo-sdk-rootstrap_3.0_armel.tgz ! ! Doing "sb-reinstall" activates the armel C-library that comes ! with the rootstrap. Now you should be able to start the Hildon Application Framework in ARMEL target inside Scratchbox by running the "af-sb-init.sh start" command. 3.2.3 Setting up the X86 target inside Scratchbox ! This step is part of manual installation. The maemo installer ! script will take care of this step for you. There is two ways how you can setup a compilation target. You can use the sb-conf command or you can use the new sb-menu command. This example uses the sb-conf command. The settings for X86 target are: Compiler: cs2005q3.2-glibc-i386 Devkits: perl, doctools, debian Note: The target name can be chosen freely. This example uses SDK_X86. Run the following sb-conf commands inside scratchbox: [sbox-: ~/ ] > sb-conf setup SDK_X86 --compiler=cs2005q3.2-glibc-i386 \ --devkits=perl:debian:doctools [sbox-: ~/ ] > sb-conf select SDK_X86 Shell restarting... [sbox-SDK_X86: ~/ ] > sb-conf rootstrap /scratchbox/packages/maemo-sdk-rootstrap_3.0_i386.tgz Unpacking rootstrap... [sbox-SDK_X86: ~/ ] > sb-conf install --etc --devkits --fakeroot Installing fakeroot version 1.4.2... Your X86 target is now ready for use. Note: You do not need to run the "sb-reinstall" in X86-target. 3.2.4 Install Scratchbox provided virtual packages ! This step is part of manual installation. The maemo installer ! script will take care of this step for you. In addition to compilers, scratchbox provides a set of build tools such as make and autoconf. Compared to earlier releases, these build tools have been removed from maemo 3.0 'bora' release and are no longer provided with the rootstraps. Run the following command to list packages which are provided by Scratchbox: $ /scratchbox/devkits/debian/sbox-list-packages.sh -l Next you will need to create empty packages which provide the build tools provided by scratchbox. This step is necessary to make Debian package management system aware that these tools are already available and don't need to be installed from repository in order to fulfill dependencies. Create empty Debian packages for each build tool package listed by the command shown above. The package should have correct version number. Packages can be built using e.g. equivs, which is delivered in the Debian distribution. Proceed by installing these packages inside scratchbox. For example, run 'equivs-control automake.control' to create a template equivs control file. Edit the fields in this file to correspond to the actual 'automake' package. Build the package using 'equivs-build automake.control'. Install this package inside Scratchbox targets to make 'automake' build tool visible to package management system. Note that this step can be automated easily. See the maemo installer script for an example. 3.3 Nokia EUSA licensed binaries 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-SDK_X86: ~] > fakeroot apt-get install maemo-explicit and for armel [sbox-SDK_ARMEL ~] > fakeroot apt-get install maemo-explicit Now you have installed the Nokia EUSA binaries to your targets. 3.4 Completing the installation (IMPORTANT) To complete your installation you need to run the following command on both targets to update Debian package database. [sbox-SDK_ARMEL: ~] > apt-get update Running the following command will try to fix any problems with the package database. Again, run the command on both targets. [sbox-SDK_ARMEL: ~] > fakeroot apt-get -f install and then do: [sbox-SDK_ARMEL: ~] > sb-conf select SDK_X86 Hangup... Shell restarting [sbox-SDK_X86: ~] > apt-get update [sbox-SDK_X86: ~] > fakeroot apt-get -f install Now you have updated the package databases. 4. INSTALLING XEPHYR X11-SERVER =============================== You need to install Xephyr X11 server software in your computer after you have installed SB and maemo 3.0 sdk. Xephyr is an X11 server that is used in the Linux host computer. It's purpose is to provide a X11-server for the scratchbox/rootstraps environment. In a practical sense, it provides a device screen for the developer in the Linux host environment so that you can see all the maemo application windows and visuals on your Linux PC. Xephyr is not included anymore in the maemo 3.0 rootstraps and is meant to be installed to the developers host system (outside of the SB). 4.1 Getting Xephyr You can find Xephyr for example from: http://packages.debian.org/unstable/x11/xserver-xephyr On Debian-based Linux distribution you can install Xephyr doing "apt-get install xserver-xephyr" outside scratchbox. 4.2 Xephyr startup parameters Xephyr requires couple of command line parameters so that it can provide a real working window for the maemo environment. Start Xephyr outside the SB with the following parameters: $ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac In the scratchbox environment the DISPLAY variable has to be set so that it matches to the display setting given above for the Xephyr server (parameter :2 in the above example). [sbox-SDK_X86:~] > export DISPLAY=:2 After the Xephyr server is running in the Linux host you can start the UI framework like this: [sbox-SDK_X86:~] > af-sb-init.sh start This should start the Application Framework inside the Xephyr window. The command will display lots of additional debugging messages and other texts to the screen but you should finally get the UI framework up and running inside Xephyr window. 5. HOW TO FLASH THE DEVELOPER ROOTFS ==================================== NOTE: YOU DO _NOT_ NEED TO FLASH THE DEV ROOTFS TO YOUR DEVICE IN ORDER TO DO DEVELOPMENT WORK. The developer rootfs (dev rootfs) is an jffs2 filesystem image that can be flashed to the device. The dev rootfs is a limited environment and does NOT contain all of the applications that are included in the actual Product Sales Image that is flashed in the device in the factory. The name of the rootfs file is: maemo-sdk-rootfs_3.0_armel.jffs2 ! NOTE: The maemo SDK development rootfilesystems do not contain boot ! loader, kernel or initfs. Use the new "flasher" program to flash the JFFS2 image to the device. To be able to flash from Linux, you will need to run the flasher binary as root. ! NOTE: The original software image will be overwritten. ! Backup your device before flashing new images on it. For details on how to use the flasher refer to the following maemo.org wiki page. http://www.maemo.org/platform/docs/howtos/howto_use_flasher_rootfs_bora.html Happy Hacking ! --- END