Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions codeless banner

Guide to Configuring and Building Qt Extended

This document is targeted to new users who are not familiar with the Qt Extended build process. It will also help those who have used previous Qtopia/Qt Extended 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 Qt Extended Internationalization for further information.

This document assumes that packages are downloaded to ~/build/qtextended. 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 Qt Extended Build System User Guide.

Prepare the External Dependencies

The Dependencies and Prerequisites document describes the libraries, compilers and other requirements needed to build Qt Extended. 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:

    qt-extended-commercial-src-<version>.tar.gz

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 qt-extended-<version> (for this example). Note that a Qt Extended source package is a combination of Qt Extended 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/qtextended/qt-extended-<version>
    $ tar zxf ../qt-extended-language-en_GB-<version>.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 qt-extended-commercial-src-<version>.tar.gz
    qt-extended-<version>/
    qt-extended-<version>/bin/
    qt-extended-<version>/bin/at
    qt-extended-<version>/bin/installhelp
    qt-extended-<version>/bin/mkpkg
    qt-extended-<version>/bin/common.pm
    qt-extended-<version>/bin/targunzip
    qt-extended-<version>/bin/cache.pm
    qt-extended-<version>/bin/targzip
    qt-extended-<version>/bin/installpic
    ...

Everything will be unpacked from this package to the qt-extended-<version> directory. In contrast, the GB language pack:

    $ tar ztf qt-extended-language-en_GB-<version>.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/
    ...

This package has no qt-extended-<version> directory, so it should be extracted from inside the qt-extended-<version> directory.

The following sub-directories are found in qt-extended-<version>:

Sub-directoryDescription
bincontains binaries and scripts needed to build Qt Extended.
config.testscontains configuration tests for external components.
devicescontains device configuration profiles.
distcontains additional fonts for Qt Extended.
doccontains the reference documentation.
examplescontains example applications.
i18ncontains global translation files.
qtopiacore/qtcontains the Qt/Embedded (and some X11) source files.
scriptscontains additional scripts.
srccontains the Qt Extended source files.

The following files and scripts are also contained in qt-extended-<version>:

File/ScriptDescription
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 Qt Extended.

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/qtextended/qt-extended-<version>

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/qtextended
    mkdir build

The use of the QPEDIR environment variable is entirely optional. It does not affect the build in any way.

    export QPEDIR=~/build/qtextended/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 Qt Extended requires and there are two ways to handle them:

Classic handling will be familiar to anyone who has built previous versions of Qt Extended. 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.

The list of device profiles shipped with Qt Extended can be found here.

Taming the Configuration Explosion

Qt Extended has many configuration options. Qt/Embedded 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.

SoftwareCommand
Qt$QTOPIA_DEPOT_PATH/qtopiacore/qt/configure -help
Qt Embedded$QTOPIA_DEPOT_PATH/qtopiacore/qt/configure -embedded -help
Qt Extended$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

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]

The list of available device profiles can be found here.

build

Once Qt Extended is configured, building is just a matter of running bin/qbuild. 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.

install

bin/qbuild image sets up the image directory. This directory contains everything required to run Qt Extended (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 bin/qbuild image 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.

Now What?

For information about running Qt Extended refer to Running Qt Extended.

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


Copyright © 2009 Nokia Trademarks
Qt Extended 4.4.3