Building a GUI Application

1. Installing required libraries and includes

It is very important that build environment (SDK) libraries and includes are as closely matching as possible with the target. Any discrepancies can lead to errors that are very hard to track down.

There are basically three alternative approaches to installing the required libraries for GUI development onto a "clean" target within Scratchbox:

1. rootstrap

2. manual build process

3. manual package installation.

Rootstrap. Rootstrap is provided by the SDK development team and it contains prebuilt ARM libraries and all required include files. It is relatively straightforward to install - just unpack the tar archive to "targets/ARM/" directory and set up PKG_CONFIG_PATH environment variable within Scratchbox. See Installing Scratchbox - Rootstrap for more information.

Manual build process. Track down all hierarchial dependencies between different software packages, download the latest library sources, and build and install them in the correct order. This is a very tedious process and not viable without a tool to automate it.

Manual package installation. This approach requires the use of the target platform package manager, such as ipkg on Familiar. There is a possibly outdated shell script version of ipkg available for the desktop platform (see handhelds.org Wiki for more information). As in the manual build process, all interdependencies between different packages still have to be tracked down. Once all required (ARM) packages are known, they are installed inside the SDK using the above-mentioned package manager. This provides the necessary libraries. Unfortunately, the include files need to be obtained separately, as "-devel" packages are usually not available for ARM, as is the case with Familiar. One option is to copy host directory "/usr/include" directly to "targets/ARM/" but you have to be very careful to match lib and include versions of each library.

2. Evaluating existing applications

One of the strengths of Scratchbox is the ease of porting existing applications onto embedded Linux platforms. These applications ore originally designed to run on an x86 personal computer. They are modified to fit the target device limitations and then compiled for the ARM processor using the SDK.

For this case study, the available GPL-licensed text editor projects were evaluated. A good catalog of Open Source Software is available at Freshmeat. From the dozen or so initial possibilities the following candidates were downloaded for further inspection: bluefish, erwin, gedit, gnotepad, gtk2edit, manyapad and mp (minimum profit).

Most of the projects were rejected because of their library requirements. Gedit and manyapad require full Gnome libraries, Erwin needs libxml2, and gnotepad and mp are based on older version of Gtk (1.2). The remaining editor, gtk2edit, was chosen as it is simple enough and has no other library requirements besides Gtk (2.0).

3. Build issues

In the beginning of the study there was some trouble when trying to configure and build the gtk2edit project under SDK ARM target. Eventually all problems resolved down to libraries and includes, as very often is the case.

Important things that you should check before building a project:

1. pkg-config installation

2. libraries and versions

3. library dependencies.

Pkg-config installation . Gtk+-2.0 and many other recent libraries require pkg-config package metainformation manager. Related .pc files are usually stored in "/usr/lib/pkgconfig", make sure this directory exists. You may have to export "PKG_CONFIG_PATH=/usr/lib/pkgconfig" environment variable as well.

Libraries and versions. Make sure libraries, includes and pc files exist for all required libraries, and their versions match. A version mismatch caused many of our troubles, as the .so files were newer than the include files that had been copied over from another installation.

Library dependencies. Try to find out the full library dependency tree for you project, so it is easier to start looking for any missing libraries.

Some problems are quite hard to find. For example, when trying to manually compile something that uses Glib the precompiler repeatedly reported include file errors. Include path was checked several times and it was confirmed that it contains "/usr/include/glib-2.0/". It turned out that one include file resides in "/usr/lib/glib-2.0/include/" instead which is quite illogical.

It would be great to have a generic configure/make/gcc "error output deciphering tool". The build process may report hundreds of errors when just one of the first include files is missing. Instead, it would be ideal if it just stopped and pointed out which library or package is missing. If a healthy source package that compiles and builds on the host platform generates screenful after screenful of errors within the SDK, you should suspect a library problem.

See Peter Seebach's article "Debugging configure - What to do when programs won't compile" for help on typical configuration and build issues.

4. Porting

The single most important thing to consider when porting a project for a target like ours is the user interface. You must take the limitations imposed by the physical size of the system into account. Also, input methods are noticeably different between a desktop computer and a PDA. You should consider the usage situation as well: does a desktop application provide all required functionality when it is used in a PDA setting? Is there some excess functionality that could be removed?

For this study we modified the original text editor as little as possible. However, we were forced to modify or remove some of the dialogs, as they were too large for the PDA screen.

5. Testing

There are several different ways to test a GUI application:

1. configure and build outside SDK, test on development host

2. configure and build inside SDK on PC target, test on development host

3. configure and build inside SDK on ARM target, test using CPU transparency (local or remote X server)

4. configure and build inside SDK on ARM target, test by copying files manually (local or remote X server).

All of these approaches have been verified to work. All of them can also be used on a single project; in the early phase it is more effective to do development and testing cycles on the desktop PC, whereas final testing must be done on actual production platform on the target device.

Testing the software within the SDK is an iterative process. Before testing a full GUI application, it is recommended that basic command line and Gtk helloworld tests are run. This way the operation of the system, libraries and CPU transparency setup are first verified.

6. Packaging

Creating a Debian .deb package for the text editor application is quite straightforward. The SDK environment includes all required packaging applications, so it is basically ready for Debian packaging out-of-the-box. However, some configuration work is required. These environment variables need to be set:

export PKG_CONFIG_PATH=/usr/lib/pkgconfig export SBOX_DPKG_INST_ARCH=arm

You may also need to move the autotools m4 file from project root into "m4/" directory to enable proper source code configuration. Once created, the package can be installed on the target device using the ipkg package manager.