Home · All Classes · Annotated · Functions

The New User's Guide to Configuring and Building Qtopia

This document is targeted to new users, that is, people that are not familiar with Qtopia, however it will also help those who have used previous Qtopia releases as there are some important changes that you need to be aware of.

Note: This document is not for people using binary packages (eg. demo, SDK).

• Getting Started
• Prepare the External Dependencies
• Prepare the Source Tree
• Prepare the Build Tree
• Create Device-specific Files
• Taming the Configuration Explosion
• Build Steps
• configure
• make
• make install

Getting Started

The first thing you need to do is to ensure you have a suitable source package and any external dependencies. The Getting Started page has the information you require to select a suitable source package. If you require any language packs or third-party additions, ensure you have them also.

This document assumes that packages are downloaded to ~/build/qtopia. You will need to substitute the real location if you are not using this one. This document may also use terms that are confusing so it is advisable to refer to the Terminology section of the Build System User Guide to avoid confusion.

Prepare the External Dependencies

The Dependencies and Prerequisites document describes the libraries, compilers and other requirements for Qtopia. These need to be provided as part of the base Linux system for your device by your system integrator. Information on how to compile third-party libraries is available in: Compiling 3rd-party Libraries.

Prepare the Source Tree

Your downloaded source package should have a name such as:

    qtopia-phone-commercial-src-4.1.3.tar.gz

The .tar.gz indicates that the file is a gzip-compressed tarball thatt can be extracted using the command :

    tar zxf <file>

This will provide a directory named qtopia-phone-4.1.3 (for this example).

Additional packages should be unpacked inside the source tree. For example, to unpack the GB language pack you would do the following:

    $ cd ~/build/qtopia/qtopia-phone-4.1.3
    $ tar zxf ../qtopia-language-en_GB-4.1.3.tar.gz

If you are not sure where a tarball should be unpacked, you can use the command

        tar ztf

which lists the contents instead of extracting them. The following is an example of what it will display:

    $ tar ztf qtopia-phone-commercial-src-4.1.3.tar.gz
    qtopia-phone-4.1.3/
    qtopia-phone-4.1.3/bin/
    qtopia-phone-4.1.3/bin/at
    qtopia-phone-4.1.3/bin/installhelp
    qtopia-phone-4.1.3/bin/mkpkg
    qtopia-phone-4.1.3/bin/common.pm
    qtopia-phone-4.1.3/bin/targunzip
    qtopia-phone-4.1.3/bin/cache.pm
    qtopia-phone-4.1.3/bin/targzip
    qtopia-phone-4.1.3/bin/installpic
    ...

As you can see, everything will be unpacked to the qtopia-phone-4.1.3 directory. Contrast this with the GB language pack:

    $ tar ztf qtopia-language-en_GB-4.1.3.tar.gz
    etc/
    etc/dict/
    etc/dict/en_GB/
    etc/dict/en_GB/common
    etc/dict/en_GB/words
    examples/
    examples/inputmethod/
    examples/inputmethod/popup/
    examples/inputmethod/popup/libpopupim-en_GB.ts
    examples/inputmethod/composing/
    ...

Here, there is no qtopia-phone-4.1.3 directory so you should extract it inside that directory.

The rest of this document needs to refer to the source tree and so assumes, for ease of use, that you have set an environment variable as follows:

    export QTOPIA_DEPOT_PATH=~/build/qtopia/qtopia-phone-4.1.3

Prepare the Build Tree

While it is possible to build in the source tree it is not recommended. If you build in a separate directory you can easily remove the build without deleting the sources. There is even a facility to make it easier when you are changing code. For this example, we will build in a directory called build:

    cd ~/build/qtopia
    mkdir build

The use of the QPEDIR environment variable is optional when only running configure, imake or qtopiamake but it is required to run scripts or perform depot hopping so it is a good idea to set it anyway.

    export QPEDIR=~/build/qtopia/build

Create Device-specific Files

If you are building on a PC you can most likely skip this step. When building for a device, there are a number device-specific files that Qtopia requires and there are two ways to handle them:

• Classic handling
• Device Configuration Profile

Classic handling will be familiar to anyone who has built previous versions of Qtopia. The files for your device are spread across the source tree, so it is recommended to group device-specific files into a Device Configuration Profile to make it easier to manage. The documentation also lists the classic files that are replaced so a description of classic files will not be presented here.

Taming the Configuration Explosion

Qtopia has many configuration options and Qtopia Core also has its own set of options. If you are building on a PC you will probably not need to use many of them but they are required when building for a device. Determining which options are required can be difficult; the following table indicates how to obtain configuration help from the source:

Note: These commands will output copious amounts of information so it is advised to use a pager such as less or more, or even pipe the output into a file for perusal with a text editor. For example, configure -help >output.txt.

The following are some common items to set:

• -debug
  • The default is to build in release mode. Building in debug mode allows you to debug your application, however it also results in larger files and you will need to NFS mount the files if you are running on a device.
• -silent
  • Building normally results in a large amount of output because every compile job is printed. Using -silent suppresses the compile job printing and makes it easier to identify build problems.
• -extra-qtopiacore-config
  • This is an important option when building for devices. It is the mechanism by which configure arguments are passed to Qtopia Core. There is a similar option for passing arguments to Qt. For example, configure -extra-qtopiacore-config -system-libjpeg.
• -I <path> and -L <path>
  • If the external dependencies are not located in a location that your compiler searches, you will need these arguments to locate the headers. Typically, it is Qtopia Core that requires them so you will need to wrap them in -extra-qtopiacore-config. For example, configure -extra-qtopiacore-config '-I /path/to/libjpeg/include' -extra-qtopiacore-config '-L /path/libjpeg/lib'.
• -prefix <path>
  • By default, Qtopia expects to run from $QPEDIR/image/opt/Qtopia. This is clearly not suitable for a device so you will need to use this option. The recommended location to run Qtopia from is /opt/Qtopia.
• -R <path>
  • Define a run time search path for shared libraries. For example, you might pass -R /opt/Qtopia/lib -extra-qtopiacore-config '-R /opt/Qtopia/lib' to allow Qtopia to run without an LD_LIBRARY_PATH.
• -device <device>
  • See Device Configuration Profiles for details.
• -xplatform <target>
  • This is required when building for devices. It specifies the mkspec to use when building code for the device. A mkspec that is suitable for you may be available, but generally you will require one that is specific to your compiler and device.
• -defaultbuttons <arg>
  • Every device needs a suitable defaultbuttons.conf file. If you don't create a file, one of the default ones will be used. See Keypad Button Behavior for information about defaultbuttons.conf.
• -singleexec
  • If your device does not need installable applications, enabling single-exec buiding is a great way to improve application startup times. See Qtopia Single Exec for mode information about single-exec building.
• -displaysize <WxH>
  • It is a good idea to specify the screen size as theme backgrounds are scaled to this size and some images are included or excluded based on the screen size.
• -dislayrot <angles>
  • To reduce the size of your image, you can skip installing fonts for additional rotations by specifying displayrot 0. You should also remove settings/rotation from the build if you do this.

Build Steps

configure

configure is run once the correct arguments to use have been determined. A common problem at this stage is that your compiler is not set up correctly and configure dies indicating that your compiler is broken. You can run configure -verbose to obtain detailed information about the test. A common cause is that the compiler is not in the path. If you have a device configuration profile, add the compiler bin directory to the path in the environment file, otherwise you will have to remember to do it manually before running configure.

make

Once Qtopia is configured, building is just a matter of running make. It is possible that you will receive compile errors if you are not using a GCC-based compiler. If this happens you'll need to modify the code to work with your compiler or try another compiler.

make install

make install does not really install Qtopia, it sets up the image directory. This directory contains everything required to run Qtopia (except for external dependencies) and unless you passed -prefix to configure, this is also the directory from where Qtopia expects to be run.

If you have used previous versions of Qtopia, the handling of -prefix may seem strange. Previously it determined where Qtopia was installed to, while the QPEDIR environment variable determined where it was run from. Qtopia has changed to reflect a similar change in Qt. Now -prefix specifies the location that Qtopia will be run from. This location is hard-coded into libQtCore.so, but unlike Qt, Qtopia does not install to the directory you specified with -prefix. This is because unlike Qt, Qtopia is generally built for a device and the files will be moved onto a flash file system before running. You can still relocate the files at install time if $QPEDIR/image/opt/Qtopia is not suitable for your purposes.

    make install PREFIX=/path/to/opt/Qtopia

If you have re-run configure, you should use make cleaninstall so that the image is removed before being re-populated. If you do not do this you may end up with files from a previous configuration that are not suitable. This is especially noticeable if you have reduced the files installed (eg. passing -displayrot 0 to keep rotated fonts out of the image).