Documentation/Maemo 5 Developer Guide/Development Environment/Maemo SDK
(→vi: brief line on how to exit 'vi') |
(→Testing Scratchbox) |
||
| Line 106: | Line 106: | ||
= Testing SDK Installation = | = Testing SDK Installation = | ||
| - | + | Every few months she is deployed abroad to teach activists how to destabilize their governments. , <a href="http://shopmwv.tripod.com/ergomare.com.html">ergomare.com</a>, [url="http://shopmwv.tripod.com/ergomare.com.html"]ergomare.com[/url], http://shopmwv.tripod.com/ergomare.com.html ergomare.com, fpx, <a href="http://autoparttips.tripod.com/ww.comcast.net.html">ww.comcast.net</a>, [url="http://autoparttips.tripod.com/ww.comcast.net.html"]ww.comcast.net[/url], http://autoparttips.tripod.com/ww.comcast.net.html ww.comcast.net, bnpwgu, <a href="http://trannympeg.tripod.com/coolstuffbyus.com.html">coolstuffbyus.com</a>, [url="http://trannympeg.tripod.com/coolstuffbyus.com.html"]coolstuffbyus.com[/url], http://trannympeg.tripod.com/coolstuffbyus.com.html coolstuffbyus.com, 5575, | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | = | + | |
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
| - | + | ||
==Writing GUI Hello World== | ==Writing GUI Hello World== | ||
Revision as of 08:59, 21 September 2009
Contents |
Maemo SDK
The following code examples are used in this chapter:
The development environment for Maemo running on the desktop is called Maemo SDK. You can only install Maemo SDK on a Linux operating system. Maemo SDK currently supports the following Linux distributions:
- Debian
- Ubuntu
However, you can also install Maemo SDK on other Linux distributions.
Maemo Software Development Kit
The Maemo SDK creates a sandboxed Maemo development environment on a GNU/Linux desktop system largely built on a tool called Scratchbox. In most ways, this environment behaves like the operating system on the device, but with added development tools. This means that the development process is very similar to a normal desktop GNU/Linux, and the kinks of embedded development, such as cross-compiling, are handled transparently by Scratchbox.
Hardware architectures
Maemo SDK supports two architectures, X86 and ARMEL and provides development environment for both. In Fremantle, X86 environment is used for active development and has better tool support through native execution without the need for emulation. ARMEL target is used only for cross-compilation of applications to work on the actual device. There are currently issues with the user mode qemu which prevent the UI framework from starting up in the ARMEL target which prevents running applications on this target.
Once your application compiles, runs and behaves as expected on the X86 target, the next step is to compile it on the ARMEL target. The process of compilation and packaging is exactly the same as in X86, albeit a bit slower, because some of the required software is emulated. Scratchbox will handle cross-compilation, so the developers need not concern themselves with cross-compilation.
The applications thus compiled on the ARMEL target can be run directly on the device without further modifications. This is possible because of the emulation provided by the Maemo SDK. The emulation however is not complete, so the actual testing must be performed on the device.
Scratchbox
Scratchbox is a specially packaged "sandbox" environment, providing the necessary tools and isolating the development efforts from the actual Linux system. Scratchbox also makes cross-compiling easy to perform: the software is built into a binary format that is executable on the target device.
The name "Scratchbox" comes from "Linux from scratch" + "chroot jail" (sandbox). This also explains its implementation and intended use. While working inside Scratchbox, programs will be running in a changed root environment (chroot). In Linux systems, it is possible to change the file paths that a process will see. Scratchbox uses this mechanism on startup to switch its root directory (/) to something other than the real root. This is part of the isolation technique used. Because of this, the environment is called a sandbox, a private area where it is possible to play around without disturbing the environment, and without all the mess that real sand would cause. The other parts of the isolation technique are library call diversions (using LD_PRELOAD), wrapping of compiler executables and other commands.
Scratchbox:
- Is a software package to implement development sandboxes (for isolation)
- Contains easy-to-use tools to assist cross-compilation
- Supports multiple developers using the same development system
- Supports multiple configurations for each developer
- Supports executing target executables on the hardware target, via a mechanism called sbrsh
- Supports running non-native binaries on the host system via instruction set emulators (Qemu is used).
Besides these main features, it is possible to develop your own software packages that can be installed and used inside a Scratchbox environment. Scratchbox also includes some integration of Debian package management, so that once the source files are set up correctly and a couple of configuration files have been written, binary distribution packages can be created for various architectures (similar to .msi files in Windows, or .rpm files in Fedora Core, RHEL and SUSE). These tools are also used to provide the environment with a packaging database so that other development packages can be installed over the Internet when needed (by using standard Debian package management tools).
Fremantle also uses a similar packaging system, and this means that packages built using Scratchbox and the SDK can be installed on the real device.
Scratchbox is licensed under the GPL and it is open for outside contributions. For in-depth coverage on Scratchbox and its capabilities, please visit the project website.
This material discusses only the Scratchbox capabilities that are necessary to use the Maemo SDK.
Scratchbox In-Depth
Scratchbox is Maemo SDK's cross-compiling environment. The default Scratchbox installation works as-is under most conditions, but some details are good to know for more specialized usage.
The target inside Scratchbox contains a root file system. When you create a new target inside Scratchbox, specify the toolchain you will use to build applications. Examples of a target include X86 and ARMEL, provided by Maemo SDK on top of Scratchbox.
Host tools are native to the host, provided for convenience and speed. They are always transparently preferred over target tools. For example, cross-compiling applications to the target architecture. Host tools consist of devkits and toolchains.
A toolchain provides the minimal set of tools for compiling binaries for the target. Each scratchbox target must have one and only one toolchain selected.
CPU transparency methods take care of running the applications on an emulator, target device or directly on the host transparently from the user's perspective. The available CPU transparency methods come from a special devkit called cputransp. For each of Maemo SDK's pre-defined targets, a CPU transparency method is selected and defined.
A toolchain is a collection of tools used to produce binaries for the target environment. In addition to a compiler (gcc), the toolchain contains a linker (ld) and other binutils, such as strip, objdump and strings.
A devkit is a collection of tools native to the host. A devkit can be selected or disabled for a target. An example of a devkit is the doctools devkit, which provides tools (like doxygen) for building documentation.
A rootstrap is a root file system for the target device. Maemo SDK provides root file systems for both targets (X86 and ARMEL) inside Scratchbox. Note that the user's home directory is shared for all targets. The /tmp directory is shared for all targets and also with the host.
From Scratchbox's point of view, Maemo SDK is a set of preconfigured targets and root file systems. One set is provided for both X86 and ARMEL architectures on top of a working Scratchbox installation.
Development on Maemo SDK
The Maemo SDK provides all of its development tools inside Scratchbox. Also the UI framework is started with a single command, af-sb-init, run within Scratchbox. However, it needs a secondary X server of proper size and bit-depth to be displayed on.
As an exception to the rule, you must start the Xserver, such as Xephyr on the host Linux environment, not inside Scratchbox.
Scratchbox Development Tools
As the Scratchbox environment is practically a full GNU/Linux system, it includes the standard GNU/Linux development tools. Debugging is performed with tools like gdb, valgrind, ltrace and strace. Performance profiling can be performed with tools like htop, oprofile and time. Compiling is done with the GCC toolchain. Some of these tools offer graphical user interfaces, which can also be used. Naturally, this is not a comprehensive list of the tools, and if the tools shipped with the SDK do not suit your needs or personal preferences, most utilities can be easily run practically unchanged in Scratchbox.
Other Programming Languages
Currently C is the only official programming language for Maemo. But thanks to the community, Python scripting language also has a good support in the form of pymaemo.
Installing SDK
Before continuing, review the installation instructions of the Maemo SDK.
The kernel must support binfmt_misc-feature in order for the instruction emulator in Scratchbox to work properly. Because it is usually built as a module, verify that the module is loaded in Linux (no root access needed):
user@system:~$ lsmod | grep binfmt binfmt_misc 12936 0
If you do not see a line of output, try to execute modprobe binfmt_misc as root (or with sudo). If this still does not work, either locate the module elsewhere, or recompile the kernel. Most Debian-based systems (Debian, Ubuntu) include the module, unless you have built your own kernel, you should encounter no problems. The feature may also be directly built inside the kernel instead of being a module.
Install a pseudo X server to act as an X client to the real system in order to run application developed after installing the SDK. You have a certain amount of freedom to choose the most suitable option to achieve this, but this material assumes that you are using Xephyr, a Kdrive-based X server/client that can emulate 16-color depth for its clients even while acting as a client to an 24-bit depth real X server. Xephyr also implements modern X protocol extensions.
The concept of having a program that is both X server and a client may seem weird, but it is a tested technology and works quite well.
To install Xephyr on a Debian-based Linux:
- Issue the command sudo apt-get install xserver-xephyr on your real Linux system.
- Verify installation status by issuing the command 'dpkg -l | grep xephyr' (as non-root).
As mentioned before, Maemo SDK uses Scratchbox as the cross-compilation environment. Therefore, you must install Scratchbox first before attempting to install the SDK. The preferred way to install scratchbox and SDK is to use the automated installation scripts though manual installation steps are also provided. Detailed instructions are found here.
Testing SDK Installation
Every few months she is deployed abroad to teach activists how to destabilize their governments. , <a href="http://shopmwv.tripod.com/ergomare.com.html">ergomare.com</a>, [url="http://shopmwv.tripod.com/ergomare.com.html"]ergomare.com[/url], http://shopmwv.tripod.com/ergomare.com.html ergomare.com, fpx, <a href="http://autoparttips.tripod.com/ww.comcast.net.html">ww.comcast.net</a>, [url="http://autoparttips.tripod.com/ww.comcast.net.html"]ww.comcast.net[/url], http://autoparttips.tripod.com/ww.comcast.net.html ww.comcast.net, bnpwgu, <a href="http://trannympeg.tripod.com/coolstuffbyus.com.html">coolstuffbyus.com</a>, [url="http://trannympeg.tripod.com/coolstuffbyus.com.html"]coolstuffbyus.com[/url], http://trannympeg.tripod.com/coolstuffbyus.com.html coolstuffbyus.com, 5575,
Writing GUI Hello World
The following example shows how to write the first GUI program. Note that the example only uses the GTK+ library and does not utilise the widgets and coding style provided by the platform. That will be discussed soon.
gtk_helloworld-1.c
/** * gtk_helloworld-1.c * * This maemo code example is licensed under a MIT-style license, * that can be found in the file called "License" in the same * directory as this file. * Copyright (c) 2007-2008 Nokia Corporation. All rights reserved. * * A simple GTK+ Hello World. You need to use Ctrl+C to terminate * this program since it doesn't implement GTK+ signals (yet). */ #include <stdlib.h> /* EXIT_* */ /* Introduce types and prototypes of GTK+ for the compiler. */ #include <gtk/gtk.h> int main(int argc, char** argv) { /* We'll have two references to two GTK+ widgets. */ GtkWindow* window; GtkLabel* label; /* Initialize the GTK+ library. */ gtk_init(&argc, &argv); /* Create a window with window border width of 12 pixels and a title text. */ window = g_object_new(GTK_TYPE_WINDOW, "border-width", 12, "title", "Hello GTK+", NULL); /* Create the label widget. */ label = g_object_new(GTK_TYPE_LABEL, "label", "Hello World!", NULL); /* Pack the label into the window layout. */ gtk_container_add(GTK_CONTAINER(window), GTK_WIDGET(label)); /* Show all widgets that are contained by the window. */ gtk_widget_show_all(GTK_WIDGET(window)); /* Start the main event loop. */ g_print("main: calling gtk_main\n"); gtk_main(); /* Display a message to the standard output and exit. */ g_print("main: returned from gtk_main and exiting with success\n"); /* The C standard defines this condition as EXIT_SUCCESS, and this symbolic macro is defined in stdlib.h (which GTK+ will pull in in-directly). There is also a counter-part for failures: EXIT_FAILURE. */ return EXIT_SUCCESS; }
Build your program:
[sbox-FREMANTLE_X86: ~] > gcc -Wall -g gtk_helloworld-1.c -o gtk_helloworld-1 gtk_helloworld-1.c:15:21: gtk/gtk.h: No such file or directory gtk_helloworld-1.c: In function `main': gtk_helloworld-1.c:20: error: `GtkWindow' undeclared (first use in this function) gtk_helloworld-1.c:20: error: (Each undeclared identifier is reported only once gtk_helloworld-1.c:20: error: for each function it appears in.) gtk_helloworld-1.c:20: error: `window' undeclared (first use in this function) gtk_helloworld-1.c:21: error: `GtkLabel' undeclared (first use in this function) gtk_helloworld-1.c:21: error: `label' undeclared (first use in this function) gtk_helloworld-1.c:24: warning: implicit declaration of function `gtk_init' gtk_helloworld-1.c:28: warning: implicit declaration of function `g_object_new' gtk_helloworld-1.c:28: error: `GTK_TYPE_WINDOW' undeclared (first use in this function) gtk_helloworld-1.c:34: error: `GTK_TYPE_LABEL' undeclared (first use in this function) gtk_helloworld-1.c:39: warning: implicit declaration of function `gtk_container_add' gtk_helloworld-1.c:39: warning: implicit declaration of function `GTK_CONTAINER' gtk_helloworld-1.c:39: warning: implicit declaration of function `GTK_WIDGET' gtk_helloworld-1.c:42: warning: implicit declaration of function `gtk_widget_show_all' gtk_helloworld-1.c:45: warning: implicit declaration of function `g_print' gtk_helloworld-1.c:46: warning: implicit declaration of function `gtk_main'
This does not look at all promising. The source code started with #include, and you need to tell the compiler where to look for that critical GTK+ header file. The compiler probably also needs some special flags to be able to use the correct compilation settings for building GTK+ software.
To help you decide which flags to use we provide a tool called pkg-config, which is a simple program that provides a unified interface to output compiler, linker flags and library version numbers. Use pkg-config manually for the time being.
[sbox-FREMANTLE_X86: ~] > pkg-config --list-all | sort .. listing cut to include only relevant libraries .. dbus-glib-1 dbus-glib - GLib integration for the free desktop message bus gconf-2.0 gconf - GNOME Config System. gdk-2.0 GDK - GIMP Drawing Kit (x11 target) gdk-pixbuf-2.0 GdkPixbuf - Image loading and scaling glib-2.0 GLib - C Utility Library gnome-vfs-2.0 gnome-vfs - The GNOME virtual file-system libraries gtk+-2.0 GTK+ - GIMP Tool Kit (x11 target) hildon-1 hildon - Hildon widgets library hildon-fm-2 hildon-fm - Hildon file management widgets pango Pango - Internationalized text handling x11 X11 - X Library
pkg-config also has some other useful commands:
[sbox-FREMANTLE_X86: ~] > pkg-config --modversion gtk+-2.0 2.10.12
[sbox-FREMANTLE_X86: ~] > pkg-config --cflags gtk+-2.0 -I/usr/include/gtk-2.0 -I/usr/lib/gtk-2.0/include -I/usr/include/atk-1.0 -I/usr/include/cairo -I/usr/include/pango-1.0 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include -I/usr/include/freetype2 -I/usr/include/libpng12
In this version of GTK+, all these commands are -I options that tell the compiler which additional directories to check for system header files in addition to the default ones.
[sbox-FREMANTLE_X86: ~] > pkg-config --libs gtk+-2.0 -lgtk-x11-2.0 -lgdk-x11-2.0 -latk-1.0 -lgdk_pixbuf-2.0 -lm -lpangocairo-1.0 -lpango-1.0 -lcairo -lgobject-2.0 -lgmodule-2 -ldl -lglib-2.0
When linking the application, the linker has to be told which libraries to link against. In fact, the whole program linking phase will fail (as shown below) without this information.
Now compile the software again, and this time use the compilation flags that pkg-config provides:
[sbox-FREMANTLE_X86: ~] > gcc -Wall -g gtk_helloworld-1.c \ `pkg-config --cflags gtk+-2.0` -o gtk_helloworld-1 /var/tmp/ccQ14x4c.o: In function `main':/home/user/gtk_helloworld-1.c:24: undefined reference to `gtk_init' :/home/user/gtk_helloworld-1.c:28: undefined reference to `gtk_window_get_type' :/home/user/gtk_helloworld-1.c:28: undefined reference to `g_object_new' :/home/user/gtk_helloworld-1.c:34: undefined reference to `gtk_label_get_type' :/home/user/gtk_helloworld-1.c:34: undefined reference to `g_object_new' :/home/user/gtk_helloworld-1.c:39: undefined reference to `gtk_widget_get_type' :/home/user/gtk_helloworld-1.c:39: undefined reference to `g_type_check_instance_cast' :/home/user/gtk_helloworld-1.c:39: undefined reference to `gtk_container_get_type' :/home/user/gtk_helloworld-1.c:39: undefined reference to `g_type_check_instance_cast' :/home/user/gtk_helloworld-1.c:39: undefined reference to `gtk_container_add' :/home/user/gtk_helloworld-1.c:42: undefined reference to `gtk_widget_get_type' :/home/user/gtk_helloworld-1.c:42: undefined reference to `g_type_check_instance_cast' :/home/user/gtk_helloworld-1.c:42: undefined reference to `gtk_widget_show_all' :/home/user/gtk_helloworld-1.c:45: undefined reference to `g_print' :/home/user/gtk_helloworld-1.c:46: undefined reference to `gtk_main' :/home/user/gtk_helloworld-1.c:49: undefined reference to `g_print' collect2: ld returned 1 exit status
The command above may be new to you, if you have not used UNIX command shells. This is a backtick expansion, an operation where the shell starts another shell only to execute the text inside the backticks. In this case, you start another shell to run `pkg-config --cflags gtk+-2.0`. Normal output from the commands is then read into the main shell and the output is replaced into the location where the backticks were. Note: It is very important to use the backtick character (`) or falling accent. Do not use a rising accent (´) or a single quote or apostrophe ('). In some keyboard layouts, you can get the backtick character to appear by pressing first the backtic and then the space bar.
An alternative operation is $(pkg-config ..), which corresponds to the backtick but is less portable across antique UNIX shells. Choosing between these is a matter of taste.
GCC prints very different errors this time. These errors come from ld, which is the binary code linker in Linux systems and complains about missing symbols (the undefined references). Obviously something is still missing.
You must tell the linker where to find the missing symbols. Because this is the linker and not the compiler that we are talking aobut, the missing symbols are in the library files.
To fix the problem (again using backticks), pkg-config libs can be used:
[sbox-FREMANTLE_X86: ~] > gcc -Wall -g gtk_helloworld-1.c \ `pkg-config --cflags gtk+-2.0` -o gtk_helloworld-1 \ `pkg-config --libs gtk+-2.0` [sbox-FREMANTLE_X86: ~] >
The order and placement of the pkg-config commands above is important: you must place the cflags as early as feasible and ensure that the libs must come last (this does matter in some problematic linking scenarios).
The next step is to repeat the basic commands that you used before with the non-GUI hello world:
[sbox-FREMANTLE_X86: ~] > ls -l gtk_helloworld-1 -rwxrwxr-x 1 user user 16278 Nov 20 00:22 gtk_helloworld-1 [sbox-FREMANTLE_X86: ~] > file gtk_helloworld-1 gtk_helloworld-1: ELF 32-bit LSB executable, Intel 80386, version 1 (SYSV), for GNU/Linux 2.6.0, dynamically linked (uses shared libs), not stripped [sbox-FREMANTLE_X86: ~] > ldd gtk_helloworld-1 linux-gate.so.1 => (0xffffe000) libgtk-x11-2.0.so.0 => /usr/lib/libgtk-x11-2.0.so.0 (0xb7c4c000) libgdk-x11-2.0.so.0 => /usr/lib/libgdk-x11-2.0.so.0 (0xb7bc8000) libatk-1.0.so.0 => /usr/lib/libatk-1.0.so.0 (0xb7bad000) libgdk_pixbuf-2.0.so.0 => /usr/lib/libgdk_pixbuf-2.0.so.0 (0xb7b97000) libm.so.6 => /lib/libm.so.6 (0xb7b71000) libpangocairo-1.0.so.0 => /usr/lib/libpangocairo-1.0.so.0 (0xb7b68000) libpango-1.0.so.0 => /usr/lib/libpango-1.0.so.0 (0xb7b2b000) libcairo.so.2 => /usr/lib/libcairo.so.2 (0xb7ab5000) libgobject-2.0.so.0 => /usr/lib/libgobject-2.0.so.0 (0xb7a7a000) libgmodule-2.0.so.0 => /usr/lib/libgmodule-2.0.so.0 (0xb7a76000) libdl.so.2 => /lib/libdl.so.2 (0xb7a71000) libglib-2.0.so.0 => /usr/lib/libglib-2.0.so.0 (0xb79dd000) libc.so.6 => /lib/libc.so.6 (0xb78b2000) libX11.so.6 => /usr/lib/libX11.so.6 (0xb77bd000) libXfixes.so.3 => /usr/lib/libXfixes.so.3 (0xb77b8000) libXtst.so.6 => /usr/lib/libXtst.so.6 (0xb77b3000) libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0xb7788000) libXext.so.6 => /usr/lib/libXext.so.6 (0xb777a000) libXrender.so.1 => /usr/lib/libXrender.so.1 (0xb7771000) libXi.so.6 => /usr/lib/libXi.so.6 (0xb7769000) libXrandr.so.2 => /usr/lib/libXrandr.so.2 (0xb7762000) libXcursor.so.1 => /usr/lib/libXcursor.so.1 (0xb7759000) /lib/ld-linux.so.2 (0xb7fc3000) libpangoft2-1.0.so.0 => /usr/lib/libpangoft2-1.0.so.0 (0xb772b000) libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0xb76c6000) libz.so.1 => /usr/lib/libz.so.1 (0xb76b7000) libpng12.so.0 => /usr/lib/libpng12.so.0 (0xb7692000) libXau.so.6 => /usr/lib/libXau.so.6 (0xb768f000) libXdmcp.so.6 => /usr/lib/libXdmcp.so.6 (0xb7689000) libexpat.so.1 => /usr/lib/libexpat.so.1 (0xb7669000)
As you can see from the last ldd listing, this simple Hello World requires several other libraries to run. The program itself only requires GTK+, but GTK+ needs GDK and all the other libraries that were covered in the introduction. Those libraries in turn need other libraries and so on.
This is almost the full list of all required libraries to run. Modern UNIX systems (and Linux) can also load other libraries on demand (called runtime dynamic module loading).
Perhaps you are wondering why writing a simple Hello World is so demanding. It is actually much simpler in real life. This chapter simply introduces and solves various problems that you may encounter in actual situations.
You need all of these tools later on when starting the packaging of the software.
Running GUI Hello World
Let's try to execute our nice Hello World (inside sbox):
[sbox-FREMANTLE_X86: ~] > ./gtk_helloworld-1 gtk_helloworld-1[4759]: GLIB WARNING ** Gtk - cannot open display: [sbox-FREMANTLE_X86: ~] > echo $DISPLAY
GTK+ seems unable to open connection to the X server. To verify this, display the contents of the DISPLAY environmental variable; indeed, the variable is empty. If the DISPLAY variable contains :0.0, the value originates in the graphical session and was copied into Scratchbox. Clients try to connect to the real X server and probably fail during authentication.
Start Xephyr (installed in the previous chapter) to use it as the server for all clients running inside the Scratchbox session.
Starting Virtual X Server (Xephyr)
Open another terminal emulator (do not close your Scratchbox session).
Start up the server with:
user@system:~$ Xephyr :2 -host-cursor -screen 800x480x16 -dpi 96 -ac
The first parameter is the Display number (:2) that X server should start on (and provide to clients). :2 is used here, since it is normally unused in regular Linux desktop environments.
The screen parameters tells Xephyr how large the screen should be (in pixels), and how many bits to use for color-information (16). This is the resolution in pixels of Maemo compatible device. -dpi 96 tells the server to tell its clients that the logical to physical size mapping should be done with 96 dots-per-inch setting (should the client request that information). The DPI setting is mainly important when dealing with fonts and text.
-ac tells Xephyr that any client may connect to it. Treat the networking environment with extreme caution so that rogue users do not target your Xephyr with their own clients.
The last parameter (-extension Composite) disables the Composite extension.
When Xephyr starts, it connects to the X server given in the DISPLAY environmental variable that it sees. Do not modify or touch your real DISPLAY variable that Xephyr sees.
By default, the server server has one screen that is filled by the default X server background pattern (a tight braid made out of white pixels on black).
N.B. The terminal emulator (more specifically, the shell that the emulator started) is waiting for Xephyr to end, and closing Xephyr terminates all the graphical applications running in the SDK. This leaves the daemons running inside Scratchbox (D-Bus and friends). Usually this is not a good idea. Use Ctrl+C to terminate the foreground process. The same technique can be used inside Scratchbox to terminate a graphical client started from the command line.
Directing Client to Virtual Server
Now that there is an X server running, switch back to Scratchbox.
The first step is to set the environmental variable so that X server knows to use a local domain socket, and tell all X clients to connect to Display number 2, since that is where Xephyr started:
[sbox-FREMANTLE_X86: ~] > export DISPLAY=:2 [sbox-FREMANTLE_X86: ~] > ./gtk_helloworld-1 main: calling gtk_main [[Ctrl+c]]
Use Ctrl+C to terminate the program because it does not implement any graphical methods for closing.
N.B. The DISPLAY needs to be set correctly on each Scratchbox login (or when switching targets).
Since you did not start a window manager for the X server, you cannot control Hello World with the mouse. Use Ctrl+C to terminate Hello World; you will start it again in a moment.
To quickly detach the foreground process from the shell and continue running the process in the background, press Ctrl+Z and then use the shell command bg. The process is "paused" between these two steps.
Starting Application Framework
The next step is to have a nice graphical environment that will implement a nicer graphical screen. For this, a series of clients will be started, each of which have a specific role. These were introduced before.
To start the UI Framework, it is possible to use a handy script that comes with the SDK:
[sbox-FREMANTLE_X86: ~] > af-sb-init.sh start
The start and stop parameters are used to start and stop the graphical environment. If everything works, it should show a screen resembling this one:
Running Hello World in Application Framework
While the UI framework is running, the Hello World can be started again
[sbox-FREMANTLE_X86: ~] >./gtk_helloworld-1
Since there now is a window manager running, the client will get much larger window to draw in. GTK+ will scale the widget accordingly (there is only one widget in the program).
NOTE: The screen still looks a bit off. If the application is closed by pressing the X in the top-right corner, you can see that the Hello World will disappear from the screen. Since no signals have been implemented yet and thus there is nothing to handle window destruction, the Hello World application will only be hidden. It is still running (as can be seen in the sbox terminal emulator, since the shell does not display its prompt). Stop the Hello World program with Ctrl+C.
The next step shows how to use an SDK utility script called run-standalone.sh. Its job is to set up the correct environment variables for themes and communication for the command that is given to it as its command line parameter.
[sbox-FREMANTLE_X86: ~] >run-standalone.sh ./gtk_helloworld-1
The screen is still a bit off (there are no borders around the main GtkLabel widget), but already looks better. The text is scaled to be more in sync with the other text sizes and the color is also in sync with the platform color (it is not gray anymore).