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.

## 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 "<PROJECT_LIST> += <component>" and to remove a component from a Project use "<PROJECT_LIST> -= <component>".

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.