maemo SDK+: User Guide

Release Information

Project: maemo SDK+

Version: 0.9.99.29

Baseline: baseline neutral

Date: 2009-03-09


1. Introduction

1.1 About maemo SDK+

Maemo SDK+ RC-4 supports cross-compilation and source package building and an armel and X86 runtime-support for running maemo ARM and X86 binaries in Linux PC side.

If you have not yet installed maemo SDK+, please, do it first. Read the Installation document.

This user guide is for maemo SDK+ RC-4 core package. It shows how to use the maemo command line environment to build software for maemo devices.

1.2. Cross-Development and SDK

Maemo SDK+ provides a cross-development environment for Nokia's maemo based devices. Cross-development differs from ordinary application development since applications are build and run on different hardware. In ordinary application development (see picture below) the development process is started with development environment installation. Then an initial application is developed using editing tools. When the application development has reatched a point in which it is buildable it is build using build tools. If the build was successful the application is then either installed first, or, run directly to see what happens. From that the application is then developed further and the process continues with a new build.

Cross-development, however, is more complicated. We have a development workstation (host computer) in which the software is build and a specific target device like Nokia N810 in which the final application is eventually run on. The target device runs a specific operating system version which need to match with the build environment. In addition, we have a simulated runtime environment running in host in which the application can be run without installing it into an actual device. The simulated runtime environment is provided to just speeds up debugging.

Thus, in cross-development we have multiple universes. The SDK+ itself is installed into a host universe which consists of whatever exists on the developer's workstation. The cross-compilation universe consists of target device libraries and header files (target device rootstrap) and tools to specificly capable of building software for that target device. The third universe is the execution universe which provides means to install and run target software. In fact we have two different execution universes: the actual target device runtime and simulated runtime on the developer workstation.

When using maemo SDK+ the application editing is done in the host universe. You can use whatever editor your host provides to write software. Unlike in old Scratchbox 1 based maemo SDK you can place the file you edit wherever in our file system; the files do not have to be placed "inside a box".

To build software you need to enter into the build universe of Scratchbox 2. In the build universe special tools and cross-compiler is used to build software using a specific target rootstrap. To enter into the build universe just add sb2 command line prefix into each given command (if the build is to be done for the default rootstrap). For instance, sb2 make could be used to run make, or sb2 dpkg-buildpackage -rfakeroot -d to build a Debian package.

To execute the application you can either copy and install it into a target device, or, run it under simulation. If you choose to run it under simulator and the application has a graphical user interface you need to start the simulated maemo framework first by using the maemo-runtime start command. To enter commands for the simulated runtime unverse use sb2 -e prefix with each command (you can also use maemo-sdk enter runtime to enter the sb2 runtime mode). If you need sudo privileges for any operation (like application installation) use sb2 -eR (or maemo-sdk enter sudo-runtime).

1.3 Cross-compilation Universe

In the Scratchbox 2 cross-compilation universe system calls related to file system access are remapped so that build tools are taken from a specific build environment, libraries, header files, aclocal files etc. are taken from a target rootstrap, and source code to be compiled are taken as is, from the host.

By remapping file access we mean modifing the actual file path of the original call. For example, if we have a file execution access /usr/bin/bison it is converted to /opt/maemo/dists/etch/usr/bin/bison before the launch happens (all build tools are taken from a build tool distribution). Another example could be an access to library /usr/lib/libc.a which is converted to ~/.maemo-sdk/rootstraps/armel/diablo4.1.2_armel/usr/lib/libc.a (taken from Diablo rootstrap). The actual remapping rules of the cross-compilation universe can be read from /usr/share/scratchbox2/lua_scripts/pathmaps/devel/00_default.lua if you have Scratchbox 2 installed.

Since the cross-compilation universe does not map one to one to the target environment the target packages should not be installed or run in there. A separate execution universe is provided which is similar to the target device environment.

1.4 Execution Universe

The execution universe is either an actual target device, or, a simulated runtime environment. In the simulated runtime environment (sb2 -e operation mode) all system calls are remapped into the target rootstrap, except access to the current working directory. By not remapping the current working directory we allow easy access to recently build packages, for instance, so that they can be installed to the target rootstrap without needing to copy the package inside the rootstrap first.

The actual remapping rules of the simulated execution universe can be read from /usr/share/scratchbox2/lua_scripts/pathmaps/emulate/00_default.lua.


2. Good to Know First

2.1 Maemo Rootstrap Directories

The maemo rootstrap manager ("maemo-rootstrap" command line tool) saves the maemo target specific rootstraps under your home directory ~/.maemo-sdk. So, please, do not remove the content of it unless you do not need the environment any more on your system.

Maemo rootstraps are archives that are stored in .tar.gz format and they contain header files, libraries and tools that are needed to compile and build applications for some specific Internet Tablet.

When developing software for some of the Nokia Internet Tablets you need to use rootstrap that matches with the content of your Tablet OS. For example do not try to use Bora rootstraps if you are developing software for N810 Tablet.

Please, keep your own software projects in a separate place (e.g. ~/MyProjects/ProjectX), not inside rootstraps. By doing this you can erase and reinstall rootstraps easily and develope for multiple rootstraps at the same time.

2.2 Maemo SDK+ Architecture

Maemo SDK+ is based on Scratchbox-2. If you are familiar with Scratchbox-1 it is good to know that technically Scratchbox-2 has pretty much nothing to do with the old Scratchbox-1. It is based on a completely new idea on how to cross-compile. Actually it is not a box any more and it certainly is not from scratch either.

When Scratchbox-2 runs software builds it takes target libraries and header files (and some other files as well) from a target rootstrap but the build tools are taken from a specific build tool environment. The build tool environment is a standard Linux distribution (currently Debian Etch). In addition, Scratchbox-2 replaces all compiler executions with a cross-compiler execution. Multiple cross-compilers can be installed at the same time and a rootstrap can be reconfigured to use a different compiler version easily.

The idea behind Scratchbox-2 is path remapping. It works like a Unix shell on top of user's shell which wraps all system calls to check if file system is accessed. Depending on the access type and Scratchbox-2 mode (build and emulation modes are available) the file path may need to be modified to access the file from the target rootstrap instead of using the original path, for instance.

Scratchbox allows you to have the standard autotool scripts (i.g. configure scripts) since the checks are run under the path mapped environment. Autotool tests and some packages generate executables during builds but that is fine since those executables are run under target emulation (using QEMU emulator in user-mode emulation mode). However, since all time consuming build tools are run natively on your host the cross-compilations run fast under Scratchbox-2.

2.3 Limitations

Please, use the following setting if you have any problems with Perl libraries during package building.

  $ export SBOX_REDIRECT_FORCE=/usr/bin/perl

The issue with Perl libraries is not a bug in the SDK+ itself but in the provided libraries in the rootstraps that Perl uses. The above command forces sb2 to use the Perl-interpreter from the Tools Distro and thus avoids the problem in the Perl that is included in the rootstraps.


3 How to Use maemo SDK+

3.1 How to install rootstraps

Once the SDK+ installation and rootstrap installation is complete you can start the development. If you have not yet installed any rootstraps, or, you want to install the latest rootstraps, please, update the network catalogue with the following command.

  $ maemo-sdk reload catalogue

This command reloads the rootstrap index file as well as tools and toolchain index files. If you do not want to use the default network location, please, specify the alternative network catalogue location with --index-url option. Now you are ready to start installing new rootstraps. A rootstrap can be installed with the following command.

  $ maemo-sdk install rootstrap
Since we did not specify the roostrap, a menu is displayed from which the rootstrap can be selected. maemo-sdk command is build in a way that if a specifier needed is not given, a menu with alternatives is shown. The same method works with all commands. The rootstrap installation command would then show, for example, the following menu:

 0 ... exit                To exit selection

final releases:
 1 ... diablo4.1.2_armel   For OS2008.43-7 (N810/N800)    2008-12-18 (289.3M)
 2 ... diablo4.1.2_i386    For OS2008.43-7 (i386 SDK)     2008-12-18 (291.6M)
 3 ... diablo4.1.1_armel   For OS2008.36-5 (N810/N800)    2008-11-13 (289.3M)
 4 ... diablo4.1.1_i386    For OS2008.36-5 (i386 SDK)     2008-11-13 (291.6M)
 5 ... diablo4.1_armel     For OS2008.23-14 (N810/N800)   2008-11-13 (280.3M)
 6 ... diablo4.1_i386      For OS2008.23-14 (i386 SDK)    2008-11-13 (282.7M)
 9 ... chinook4.0_armel    For OS2008 (Nokia N810/N800)   2007-12-20 (203.3M)
10 ... scirocco2.2_armel   For latest OS2006 (Nokia 770)  2006-12-22 (107.4M)
11 ... scirocco2.2_i386    For latest OS2006 (i386 SDK)   2006-12-07 (117.3M)
12 ... mistral2.0_armel    For older OS2006 (Nokia 770)   2006-07-05 (138.9M)

alpha releases:
 7 ... fremantle5.0alpha_armel For OS2009Alpha (armel SDK)    2008-12-08 (248.8M)
 8 ... fremantle5.0alpha_i386 For OS2009Alpha (i386 SDK)     2008-12-08 (268.8M)

Select (0..12)? 

If you now select option 2, for instance, diablo4.1.2_i386 rootstrap will be downloaded and installed.

3.2 Examples of the most often used sb2 commands

This chapter explains the most often needed and used sb2-commands that the developer uses.

The sb2 command line options are as follows:

  $ sb2 -h

Options:
    -v           display version
    -L level     enable logging (levels=one of error,warning,notice,info,debug,
                 noise,noise2,noise3)
    -d           debug mode: log all redirections (logging level=debug)
    -h           print this help
    -t TARGET    target to use, use sb2-config -d TARGET to set a default
    -e           emulation mode
    -m MODE      use mapping mode MODE
    -M file      read mapping rules from "file"
    -s DIRECTORY load mapping scripts from alternative location
    -Q BUGLIST   emulate bugs of the old scratchbox 1 (BUGLIST consists of
                 letters: 'x' enables exec permission checking bug emulation)
    -r           do not create reverse mapping rules
    -O options   set options for the selected mapping mode ("options" is
                 a mode-specific string)
    -R           use simulated root permissions (currently activates
                 "fakeroot" for this functionality)
    -S file      Write session information to "file" (see option -J)
    -J file      Don't create a new session; join an existing one (see -S) 
    -D file      delete an old session (see -S). Warning: this does not
                 check if the session is still in use!
    -W dir       Use "dir" as the session directory when creating the session
                 ("dir" must be absolute path and must not exist. N.B. long 
                 pathnames here may cause trouble with socket operations) 
    -c           When creating a session, also create a private copy
                 of target_root (rootstrap). Note that this can be
                 really slow, depending on the size of the orig.target_root
    -C dir       When creating a session, create copy of "dir" and use it as the 
                 target_root (rootstrap).
    -T dir       use "dir" as tools_root (overriding the value from config file)

All of the examples below use the default-target ie rootstrap for all operations.

./configure


  $ sb2 ./configure

Using the plain sb2 ./configure command activates the devel-mode mappings for sb2. This means that most tools that are needed during package building process are taken from the installed Tools Distro and not from the rootstrap.

Use this if you are compiling source code that comes from plain .tar.gz archives.

make


  $ sb2 make

Similar than above. This runs the make command in devel mode.

apt-get source


  $ cd ~/src/some_directory_name
  $ sb2 apt-get source your_source_package

Getting debian source packages is done using the above command. You don't need the -eR options in this use case.

dpkg-checkbuilddeps


  $ cd ~/src/your_source_package_name
  $ sb2 -eR dpkg-checkbuilddeps

The dpkg-bcheckbuilddeps command must be run with the -eR options because it installs packages into the rootstraps.

apt-get build-dep


  $ cd ~/src/your_source_package_name
  $ sb2 -eR apt-get build-dep your_source_package_name

The apt-get build-dep command must be run with the -eR options because it installs packages into the rootstraps.

Running the command without these options will fail.

dpkg-buildpackage


  $ cd ~/src/your_source_package_name
  $ sb2 dpkg-buildpackage -rfakeroot -b -us -uc

Running dpkg-buildpackage is done in the devel-mode. Above example will compile and build your package and generate .deb binary package(s).

dpkg -i


  $ cd ~/src/your_source_package_name
  $ sb2 -eR dpkg -i your_binary_package_name

Running dpkg -i is done in the emulate & fakeroot-mode. The operation needs to install packages to rootstrap and the -R flag provides the simulated sudo access.

apt-get update


  $ sb2 -eR apt-get update

Running apt-get update must be done in the emulate & fakeroot-mode.

apt-cache search


  $ sb2 -eR apt-cache search some_package_name

Running apt-cache search must be done in the emulate & fakeroot-mode.

apt-get install


  $ sb2 -eR apt-get install your_binary_package_name

Running apt-get install must be done in the emulate & fakeroot-mode.

apt-get remove


  $ sb2 -eR apt-get remove your_binary_package_name

Running apt-get remove must be done in the emulate & fakeroot-mode.

apt-get autoremove


  $ sb2 -eR apt-get autoremove your_package_name

Running apt-get autoremove must be executed in the emulate & fakeroot-mode.

In general, most operations that alter the rootstrap content must be run using the -eR options for sb2. If these options are not used sb2 will use programs from Tools Distro and will also not allow the process to write anything to the rootstrap area.

The next chapter also uses and demonstrates some of the commands explained above.

3.3 How to build software

A recommended way is to create a folder for your projects anywhere under your home directory. However, please, do NOT use the rootstrap directory as a working directory since you might later want to update the content of it with the rootstrap manager. Thus, you might want to create a working directory like the following and go into it

  $ mkdir -p ~/MyProjects/maemo
  $ cd ~/MyProjects/maemo

Now it is time to fetch a sample source code. This can be done by typing

  $ sb2 -eR -t diablo4.1.2_armel apt-get update
  $ sb2 -t diablo4.1.2_armel apt-get source maemopad

Now you should have maemopad-2.4 directory under ~/MyProjects/maemo. Note that we used the nickname diablo4.1.2_armel to explisitly specify the rootstrap we wanted to use for building. Scratchbox-2 allows you to set up a default rootstrap by typing

  $ maemo-sdk set rootstrap diablo4.1.2_armel

so we do not need to explisitly specify which rootstrap we are going to use every time. Once we have set Diablo 4.1.2 ARMEL as the default rootstrap we can build the Maemopad by typing

  $ sb2 dpkg-buildpackage -rfakeroot -d -b

This will give you a fresh maemopad_2.4_armel.deb package into ~/MyProjects/maemo directory. Copy this file to a N810 running OS2008 and install it using the application installer.

Build dependency checking can be done as well so dpkg-buildpackage can be run without -d option (or with expicit -D option). Note that it takes a minute or two when it is done for the first time since a database need to be build by collecting package information from multiple sources (from the rootstrap and build environment apt databases).

Building from source using ./configure or make commands is done the same way. Just add sb2 before any command.

  $ sb2 ./configure && sb2 make

3.4 How to install software with make

Installation using make install requires that you give the target destination directory for the command since we do not want to install the ARM binaries into our build environment. In order to specify the target rootstrap for the make install you need to check out what is the correct method of passing the destination directory for your specific Makefile. Usually it is done by setting up DESTDIR variable. Thus, the (make based) installation using maemo SDK+ is done by typing

  $ sb2 make install DESTDIR=/target_root

or, if you want to specify the rootstrap to be used explicitly

  $ sb2 -t diablo4.1.2_armel make install DESTDIR=/target_root

3.5 How to install packages into the runtime environment

If you want to use apt-get in order to install packages into the runtime just type:

  $ sb2 -eR -t diablo4.1.2_armel apt-get install maemopad

To install a newly created package, for example maemopad_2.4_armel.deb, go to the directory where the .deb file is and type:

  $ sb2 -eR -t diablo4.1.2_armel dpkg -i maemopad_2.4_armel.deb

4 Runtime debugging

4.1 Starting runtime

In order to start the runtime debugging environment just type:

  $ maemo-sdk start gui diablo4.1.2_armel

Then just wait a few seconds and you have the runtime up and running. Please, note that Xephyr might not be able to start properly if your X server does not support the color bit depth specified for the roostrap (most likely 16 bits). If the GUI did not start up you might want to force maemo-sdk to use some other color bit depth, e.g. 24 bits. This can be done with the following command:

  $ maemo-sdk set gui-bit-depth 24

4.2 Stopping runtime

In order to stop the runtime just type:

  $ maemo-sdk stop gui diablo4.1.2_armel

4.3 Entering runtime shell

In order to give shell commands for an SDK+ runtime we can either enter into a runtime shell, or, give commands one by one. It is good to understand that Scratchbox 2 can provide multiple concurrent sessions for one rootstrap. Each session has it's own /tmp folder mapping, for instance. Thus, if you use sb2 -e command directly you need to provide the session identifier as well (if your specific command requires GUI access, for instance). To make all this easy we can open a shell that accesses the same runtime session in which the previously started GUI operates by simply typing:

  $ maemo-sdk enter runtime diablo4.1.2_armel

And now when we are inside diablo4.1.2_armel session, we can launch an application by typing:

  [SB2 emulate diablo4.1.2_armel] $ run-standalone.sh maemopad

To exit the session, simply type:

  [SB2 emulate diablo4.1.2_armel] $ exit

In addition, it is possible to run commands without entering into the shell the following way:

  $ maemo-sdk enter runtime diablo4.1.2_armel 'run-standalone.sh maemopad'

4.3 Entering runtime shell as root user

Sometimes root privileges are needed for some operations. The maemo SDK+ provides a command

  $ maemo-sdk enter sudo-runtime
which operates with root prividedges. Note that sb2 -eR command does the same but is shorter.


5 Managing the build environment

5.1 Adding tools

If you need to extend the build environment to have a new tool, for example, you can use maemo-tools get command. For instance, to add Vala 0.5.7 support just type:

  $ sudo maemo-tools get vala-0.5.7

5.2 Searching available tools

In general to get a new tool into the build environment it must be available for Debian Etch. To search if the tool exists you can type:

  $ sudo maemo-tools search [toolname]

5.3 Manually extending the build environment

If the tool is not available you might want to try compiling it for Debian Etch. Just type (and replace tool with your own tool package name):

  $ cp tool.tar.gz /opt/maemo/dists/etch/tmp
  $ sudo chroot /opt/maemo/dists/etch
  $ cd /tmp
  $ gunzip tool.tar.gz
  $ tar xvf tool.tar && cd tool
  $ ./configure --prefix=/usr
  $ make
  $ make install
  $ exit

5.4 Listing installed packages

If you want to see the list of packages that have been installed to your build environment, just type

  $ sudo maemo-tools list-packages etch

If you want to display the whole configuration of the SDK+ (e.g. to be attached into a bug report, for instance) you can use the following command. This command prints the content of both the build tools environment and the rootstrap as well as the version numbers of maemo SDK+ packages.

  $ maemo-sdk show config

5.5 Changing toolchain (gcc cross-compiler) version

maemo SDK+ allows you to work with multiple toolchain versions. Currently it is recommended to use arm-2005q3 to build maemo software. If you want to use a different version, i.g. arm-2007q3, please install it first by typing:

  $ sudo maemo-sdk install toolchain arm-2007q3

The cross-compiler is fixed per rootstrap installation. If you want to change the cross-compiler for a particular rootstrap, for example diablo4.1.2_armel to use arm-2007q3, just type:

  $ maemo-sdk set toolchain diablo4.1.2_armel arm-2007q3

Changing back to arm-2005q3 is done simply by typing:

  $ maemo-sdk set toolchain diablo4.1.2_armel arm-2005q3

6 Changing configuration

6.1 Changing the default rootstrap

Changing the default rootstrap can be done by:

  $ maemo-sdk set rootstrap diablo4.1.2_armel

6.2 Autosudo

If you have set sudo properly for your username (in Ubuntu this is done by default) you can turn the autosudo method on with the following command:

  $ maemo-sdk set autosudo on

Now every time your maemo-sdk command requires super user privileges the command automatically reruns itself under sudo if you have not done it so. To disable this feature just type:

  $ maemo-sdk set autosudo off

6.3 Network catalogue index

If you want to use some other location for the network index files than the default place you can change the setting by the following command:

  $ maemo-sdk set url http://some_web_address/

If you want to restore the default URL setting just type:

  $ maemo-sdk set url default

6.4 Network proxy setting

maemo-sdk uses the http_proxy environment variable setting as a proxy when accessing the network. If you want to give a default proxy setting, which is used when http_proxy has not been set, for the maemo-sdk, just type the following command:

  $ maemo-sdk set proxy http://some_proxy_address:some_port_number

7 Feedback and further help

There are multiple ways of giving feedback about this product. If you have any problems or questions how to use SB2 based maemo SDK+ development environment please send your questions and comments to either:

* maemo SDK+ developer forum

* maemo-sdk-developers@maemo.org mailing list

* Bugs can be reported at our bug tracker

* Feature requests can be given here