Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded

Qtopia Build System

Introduction

This document describes the Qtopia build system.

Naming conventions

Acceptable directory characters

There are some limits to the acceptable characters in directories. The details are in the Build Environment document.

Requirements

Actually, other architectures/platforms and operating systems are likely to work, it's just that they're not tested. For example, Qtopia and Qtopia Desktop built fine on a PowerPC machine running Yellow Dog Linux 3.0.1.

Project Lists

There are four Project Lists in the Qtopia Build system.

Project List Description
LIBRARY_PROJECTS The list of library components that are used by both applications and plugins.
APP_PROJECTS The list of application components.
PLUGIN_PROJECTS the list of plugin and applet components.
THEME_PROJECTS the list of theme components.

The Project Lists are processed in order, such that all library components are built before any application components are built.

Project List files

Project List files can be found in $QPEDIR/src. The are used to populate the Project Lists based on the configuration of Qtopia.

File Description
general.pri Lists build components included in all Qtopia source packages. This includes all core Qtopia functionality along with those components that are released both under the GPL and under the commercial licences.
commercial.pri Lists build components that are included in the commercial Qtopia source packages, but not the GPL source packages. This file is not provided included in the GPL Qtopia source packages.
custom.pri Lists custom configuration components. The custom.pri file included with the Qtopia source packages can be extended to add components specific to device, organisation or group. The custom.pri file provided in Qtopia source packages is an example only and does not include any active build information. See Modifying Project Lists below for more information.
local.pri Lists local configuration components. The local.pri file is not shipped with any Qtopia package, and Qtopia will build without the file present. If the file is provided Qtopia will read it after custom.pri. The local.pri file enables individuals in a group to have different component lists while still sharing components specified using custom.pri.

Modifying Project Lists

The custom and local Project List files are provided for modifying the Project Lists. To add a component to a Project List use " += " and to remove a component from a Project use " -= ".

To specify more than one component pass them as a space separated list. The \ character can be used to continue the list on the following line.

APP_PROJECTS += applications/addressbook applications/calculator \
        applications/clock applications/datebook

As the Project List files are qmake project files so you can also use the conditional processing qmake provides. See the qmake manual for more information on the format of project files.

Internal build system files

Details of the automatic include process

For all qws/* qmake specs (eg. QMAKESPEC=qws/linux-generic-g++), there is an explicit include of $QPEDIR/src/config.pri if it exists.

Projects from inside the Qtopia source tree are subject to this rule but they need some processing that external projects do not. Also, Qtopia Desktop projects do not use qws/* QMAKESPEC values. To handle this, configure writes $QPEDIR/src/.qmake.cache which sets a flag and includes $QPEDIR/src/config.pri. qmake finds this file by searching all directories above the one in which the project file exists.

config.pri tells qmake to process global.pri after processing the main project file.

There are include guards on the important .pri files to ensure they are not processed more than once.

How Makefiles are used

When you type 'make', it reads the file Makefile to determine what must be done. Since Qtopia requires some differences to what qmake creates in it's output, the qmake-generated files are called Makefile.target.

It is not safe to try manually recreating Makefiles since you may overwrite the special Makefile created by configure. Re-running configure is the only supported way to recreate both Makefile and Makefile.target. However, to allow easier development, it is possible to run "make qmake" to regenerate Makefile.target. This uses a qmake-generated rule or the 'regenerate' target to recreate Makefile.target. The 'regenerate' target also recreates the special Makefile.

The special Makefile exists so that the installation destination is handled in a sane way. There are two variables, PREFIX and DPREFIX that specify the install locations for Qtopia and Qtopia Desktop. configure puts default values for these in the special Makefile but they can be overridden on the commandline (eg. make PREFIX=/opt/Qtopia DPREFIX=/opt/QtopiaDesktop).

In order to allow maximum flexibility, the special Makefile uses all of the targets defined in Makefile.target. If Makefile.target is rebuilt, the targets may no longer match what is in the special Makefile. Running 'make regenerate' will rectify this situation. Note that this is not normally a problem since the 'usual' targets are always created even if they are not available in Makefile.target.

The special Makefile turns PREFIX (or DPREFIX) into INSTALL_ROOT since that is the variable qmake uses for it's install prefix. If you do not have a special Makefile (eg. because you have manually run qmake on a project that lives outside of the depot), you must set INSTALL_ROOT to the location you want everything installed to (eg. make INSTALL_ROOT=/opt/Qtopia). It is generally better to pass the directory to configure -build (eg. configure -build /path/to/my/extra/stuff).

Using .pri includes to simplify building for Qtopia and Qtopia Desktop.

A typical project might have three project files, consisting of one .pri file and two .pro files.

Taking src/libraries/qtopiapim as an example:


Copyright © 2001-2005 Trolltech Trademarks
Qtopia version 2.1.1