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

Qtopia Build System

Introduction
Naming conventions
Acceptable directory characters
Requirements
Project Lists
Project List files
Modifying Project Lists
Internal build system files
Details of the automatic include process
How Makefiles are used
Using .pri includes to simplify building for Qtopia and Qtopia Desktop.
CONFIG values that change how your project is built.
QTOPIA_COMPAT_VER

Introduction

This document describes the Qtopia build system.

Naming conventions

.pri files are intended for inclusion by .pri or .pro files.
.pro files are directly used to generate Makefile files.

Acceptable directory characters

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

Requirements

Computer: X86, 256MB RAM and 300MB disk space
Compiler: Cross-compiler based on gcc 2.95 or later
Linux distribution: SuSE 8.0/8.2 or later, RedHat 9

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

$QPEDIR/src/config.pri is generated by the configure script and turns specified options into qmake variables. It is processed before every project file and it's values can be overwritten.
src/global.pri is processed after every project file, and contains globally applicable settings, such as how to make an ipkg, and how to link against common libs.
src/ipk_groups.pri - in most cases, one project = one ipkg. Sometimes, more then one project needs to be in an ipkg. This file specifies how to build such a package.
projects.pri marshalls the list of projects from general.pri, commercial.pri, custom.pri and local.pri.
src.pro and src-components.pro specify the projects to build. The src.pro file marshalls projects that need to be built in a specific order, while src-components.pro marshalls projects that can be built in any order. Projects from src.pro are built before projects from src-components.pro.
src.pro is the file that the top-level Makefile is generated from. It also knows how to build the ipkgs that are specified in control files because they dont have a .pro file.

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:

qtopiapim.pri lists all the files that are common between the Qtopia application and the Qtopia Desktop.
qtopiapim.pro includes qtopiapim.pri and adds Qtopia-specific configuration.
src/qtopiadesktop/libraries/qtopiapim.pro also includes qtopiapim.pri and adds Qtopia Desktop-specific configuration.

CONFIG values that change how your project is built.

Some CONFIG values affect libraries and includes used.

CONFIG value	result
qtopia	Add qtopialib and qtopiainc to CONFIG.
qtopialib	Include the Qtopia libraries. (See also QTOPIA_COMPAT_VER )
qtopiainc	Include the Qtopia includes.
pimlib	Include the Qtopia PIM libraries. (See also QTOPIA_COMPAT_VER )

There are CONFIG values to identify the types of Qtopia projects you can build. There are some typical values that are treated specially by the build system. Obviously you are not limited to these types of projects but other projects are outside the scope of this document.

CONFIG value(s)	result
qtopiaapp	A Qtopia application.
qtopiaplugin	A Qtopia plugin.
qtopiadesktop plugin	A Qtopia Desktop plugin.

Finally, there are some settings that tweak the behaviour of the build system.

Type of project	command	result
All Projects	TRANSLATIONS=	Disable use of translations for this project (ie. there are no tr() calls in the code).
qtopiaapp	CONFIG-=buildQuicklaunch	Disable quicklaunch for this project.
qtopiaplugin	QTOPIA_PROJECT_TYPE=foo	Override the default plugin type for this project. This is typically required for plugins that do not reside in the depot as the default is derived from the directory name.

QTOPIA_COMPAT_VER

You can set the QTOPIA_COMPAT_VER variable to the release of Qtopia you wish to target. This will affect the libraries that your project links against.

The effect of QTOPIA_COMPAT_VER if CONFIG contains qtopialib.

QTOPIA_COMPAT_VER	libraries
1.5	libqpe
1.7	libqpe and libqtopia
2	libqpe, libqtopia and libqtopia2

The effect of QTOPIA_COMPAT_VER if CONFIG contains pimlib.

QTOPIA_COMPAT_VER	libraries
1.7	libqpe and libqtopia
2	libqpe, libqtopia and libqtopia2

Leave QTOPIA_COMPAT_VER blank to use highest value available.

This does not stop you from using methods introduced in a later release in an older release so you will need to be careful which methods you use. If you need classes or methods from a newer release but you still want to target an older device, you can install libqtopia and/or libqtopia2 to gain the additional functionality.

Trademarks

Qtopia version 2.1.2