ZZ's blog: Bringing Chiquita Brands to Justice

ZZ's blog: Bringing Chiquita Brands to Justice

maemo 4.1.2 Diablo Development Platform

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