Home · All Classes · Grouped Classes · Annotated · Functions

Guide to Configuring and Building Qtopia

This document is targeted to new users who are not familiar with the Qtopia build process. 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

You need to ensure that you have a suitable source package and any external dependencies installed. 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. Refer to Qtopia Internationalization for further information.

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. If you are unfamiliar with any of the terms used, please refer to the Terms section of the Qtopia Build System User Guide.

Prepare the External Dependencies

The Dependencies and Prerequisites document describes the libraries, compilers and other requirements needed to build Qtopia. These need to be provided as part of the base Linux system for your device by your system integrator.

Prepare the Source Tree

Your downloaded source package should have a name such as:


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

    tar zxf <file>

This will provide a directory named qtopia-phone-4.3.0 (for this example). Note that a Qtopia source package is a combination of Qtopia and Qt sources.

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.3.0
    $ tar zxf ../qtopia-language-en_GB-4.3.0.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.3.0.tar.gz

Everything will be unpacked from this package to the qtopia-phone-4.3.0 directory. In contrast, the GB language pack:

    $ tar ztf qtopia-language-en_GB-4.3.0.tar.gz

This package has no qtopia-phone-4.3.0 directory, so it should be extracted from inside the qtopia-phone-4.3.0 directory.

The following sub-directories are found in qtopia-phone-4.3.0:

appscontains the .desktop files for Qtopia.
bincontains binaries and scripts needed to build Qtopia.
config.testscontains configuration tests for external components.
devicescontains device configuration profiles.
distcontains additional fonts for Qtopia.
doccontains the reference documentation.
etccontains settings, themes, dictionaries, etc needed for Qtopia to operate.
examplescontains example applications.
helpcontains the help files that will be installed on a device.
i18ncontains application translation files.
picscontains Qtopia and application icons and images.
qtopiacore/qtcontains the Qtopia Core (and some X11) source files.
scriptscontains additional scripts.
servicescontains Qtopia service files.
skinscontains extra QVFb skins.
soundscontains application sounds.
srccontains the Qtopia source files.

The following files and scripts are also contained in qtopia-phone-4.3.0:

LICENSEa text that describes the license that is applicable to the package. Note: For an evaluation package the LICENSE file will not be available until the configure command has been executed at least once.
LODIList Of Deliverable Items, that is, a list of all files that can be found in the package.
README.htmla basic introduction that guides the user to the help documentation.
configurethe script that is used to configure Qtopia.

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

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

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, make 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 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 Profiles to make it easier to manage. The documentation also lists the classic files that are replaced. A description of classic files will not be presented here.

Taming the Configuration Explosion

Qtopia has many configuration options. Qtopia Core 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 build configuration scripts. Click the links to see the output.

Qt$QTOPIA_DEPOT_PATH/qtopiacore/qt/configure -help
Qtopia Core$QTOPIA_DEPOT_PATH/qtopiacore/qt/configure -embedded -help
Qtopia$QTOPIA_DEPOT_PATH/configure -help

Here are a few of the configure options that are commonly used. For a complete reference you should see the links above.

Build Steps


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 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.

Note that configure should be run from the build directory. For example:

    cd $QPEDIR
    $QTOPIA_DEPOT_PATH/configure [options]


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.

Note: make cannot be run from within the <source_tree>/qtopiacore or <build_tree>/qtopiacore directories. Qtopia manages these directories and when running make manually, environment variables may not be set correctly resulting in incorrect directories being used for the build.

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).

If you did not specify a suitable -image location to configure, you can redirect where the image is placed now by specifying make install IMAGE=/over/there. A complete discussion on how the image, prefix and SDK locations are handled can be found in Image, prefix and SDK location.

Note that Qtopia 4.2 changed how -image and -prefix are handled. Please refer to Image, prefix and SDK location for an overview of how these parameters are handled in Qtopia 4.2 and above.

Now What?

For information about running Qtopia refer to Running Qtopia.

For application development, you may find the documentation on Creating and using binary SDKs to be helpful.

Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3