Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

Qtopia Build System

Introduction

This document describes the qmake-based build system used by Qtopia. More information about qmake and its syntax can be found in the qmake Manual. Information about the system used to configure and build the single-package Qtopia releases for Qtopia 2.2 and above can be found in the Single Package System page.

Naming Conventions

Acceptable Directory Characters

There are some limitations to the acceptable characters in directories, please refer to the Acceptable Directory Characters section of the Build Environment document.

Requirements

The following are the basic system requirements for building Qtopia:

Other architectures/platforms and operating systems can be used, however, they have not been tested and are not formally supported.

Project Lists

Project lists define the library components for a particular project or application. The lists are processed in order, such that all library components are built before application components. The four project lists in the Qtopia Build system are shown in the following table:

Project List Description
LIBRARY_PROJECTS Lists library components that are used by both applications and plug-ins.
APP_PROJECTS Lists application components.
PLUGIN_PROJECTS Lists plug-in and applet components.
THEME_PROJECTS Lists theme components.

Project List Files

Project list files identify the components that should be built. The project list files are located in $QPEDIR/src and include the following:

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

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 is used to continue the list on the following line, for example:

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

It is not recommended to have a project listed more than once as it will build multiple times and will result in warnings from \make. To check if a project is already added use:

    <PROJECT_LIST> *= <component> 

Core libraries

When adding a core library (ie. a library that other Qtopia libraries depend on), additional steps are required as follows:

  1. Ensure that a library is inserted into the list before any libaries that depend on it. Libraries are processed in the order that they appear in the LIBRARY_PROJECTS variable. Some important Qtopia libraries are listed in a separate CORE_LIBRARY_PROJECTS variable to allow them to be easily prepended to the list of libraries by projects.pri.

    For example:

        # add my phone extension lib before qtopiaphone
        CORE_LIBRARY_PROJECTS~=s,(libraries/qtopiaphone),libraries/myphonebase \1,
        # add my media extension lib after mediaplayer
        LIBRARY_PROJECTS~=s,(libraries/mediaplayer),\1 libraries/mymediaext,
    

  2. Ensure the library is added to src/order.cfg so that configure can process it in the correct order. This file is used as configure cannot read the build system files but is still required to process .pro files in a suitable order.

Internal Build System Files

The internal build system files are described in the following table:

File Name Description
$QPEDIR/src/config.pri This file is generated by the configure script and converts specified options into qmake variables. It is processed before every project file and its values can be overwritten.
src/global.pri This file is processed after every .pro files and contains all the code that makes the Qtopia Build System work. It handles many tasks including:
  • how to make an ipkg
  • how to link against common libraries
src/ipk_groups.pri This file specifies how to build a package that contains more than one project.

In most cases: one project = one ipkg.

projects.pri This file collates the list of projects from:
  • general.pri
  • commercial.pri
  • custom.pri
  • local.pri
src.pro This file organises projects that need to be built in a specific order. It is also used to create the top-level Makefile and to build ipkgs that do not have a .pro file.
src-components.pro This file organises projects that do not need to be built in a specific order. It is called from src.pro.

Automatic Include Process Details

An automatic include is used to reduce the amount of code required in a .pro file and to keep the syntax compatible with Qtopia 1.x and below.

This process is required as configure creates the file $QPEDIR/src/.qmake.cache that causes projects inside the Qtopia source tree to read $QPEDIR/src/config.pri which is not useful for projects that are outside the Qtopia source tree, such as third-party applications.

For all qws/* qmake specification files such as, QMAKESPEC=qws/linux-generic-g++, there is an explicit include of $QPEDIR/src/config.pri if it exists. If you create your own qws/* specification file, you must add the same directive to your file or third party applications will not be able to build against your Qtopia tree.

To ensure that config.pri is not processed more than once, it has an include guard similar to how C headers use #ifndef FOO, #define FOO, ..., #endif.

Makefiles

Qtopia is based on qmake but not exclusively. Projects that configure processes are given two Makefiles:

File Purpose
Makefile.target This file is generated by qmake.
Makefile This file holds the Qtopia extensions.

All of the targets available in Makefile.target are available in Makefile. In the case where Makefile.target has not yet been created, only the common targets are available.

It is not safe to manually create or update a Makefile with qmake. The command make qmake can be used to update both the Makefile and Makefile.target, alternatively, configure can be run again and it will re-create both files.

Note: Third party applications may only use a qmake-generated Makefile and Qtopia extensions are not available in this case.

Qtopia extensions

Qtopia makefiles contain a number of Qtopia extensions which facilitate the following behavior:

  1. make install installs a number of files to a particular location. Howerver in some circumstances the location may need to be overridden at install time. To override the -prefix and -dprefix values passed to configure run the following command:
        make install PREFIX=/path/to/image DPREFIX=/path/to/dimage
    

    Makefile passes the appropriate values to Makefile.target as INSTALL_ROOT. Third-party applications using a single makefile should pass the location of the image with this variable:

        make install INSTALL_ROOT=/path/to/image
    

  2. Running the command
        make qmake
    
    from a sub-directory target causes all sub-projects to be re-processed, however this can be avoided by running
        make regenerate
    

  3. Qtopia supports shadow building which is a build where the generated files are located in a build tree that is separate from the source files. One disadvantage of this system is that you must have two terminals open, one for editing files and one for building.

    Makefile has a check that allows you to run make from the source tree and have the project built in the build tree. This feature is known as depot hopping. To take advantage of this feature it is necessary to setup shadow building:

Simplifying Qtopia Desktop Support with .pri Files

A typical project that builds under Qtopia and Qtopia Desktop might have several project files. For example the Qtopia PIM project comprises:

File Description
src/libraries/qtopiapim/qtopiapim.pri Lists all the files that are common between Qtopia and Qtopia Desktop.
src/libraries/qtopiapim/qtopiapim.pro Includes qtopiapim.pri and adds Qtopia-specific configuration information.
src/qtopiadesktop/libraries/qtopiapim.pro Includes qtopiapim.pri and adds Qtopia Desktop-specific configuration information.

Configuration Variables

Configuration variables are used to modify the way that a project is built. Some of the effects of changing configuration variables include:

The following sections provide examples of configuration variables and the affect that they have.

CONFIG

The following table provides examples of CONFIG variable values that determine the libraries and includes used in a Qtopia build:

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)

The following table provides examples of CONFIG variables to identify the type of Qtopia project to build:

Value Result
qtopiaapp Qtopia application
qtopiaplugin Qtopia plug-in
qtopiadesktop plugin Qtopia Desktop plug-in
Other project types are available, however they are outside the scope of this document.

Other Variables

The following table provides examples of variables that alter the behavior of the build system:

Project Type Command Result
All Projects TRANSLATIONS= Disable use of translations for this project.
qtopiaapp CONFIG-=buildQuicklaunch Disable quicklaunch for this project.
qtopiaplugin QTOPIA_PROJECT_TYPE=foo Override the default plug-in type for this project. This is typically required for plug-ins that do not reside in the depot as the default is derived from the directory name.

QTOPIA_COMPAT_VER

The QTOPIA_COMPAT_VER variable is set to the target release of Qtopia, which in turn affects the libraries that the project links against.

The following table shows the effect of QTOPIA_COMPAT_VER when CONFIG contains qtopialib.

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

The following table shows the effect of QTOPIA_COMPAT_VER when CONFIG contains pimlib.

QTOPIA_COMPAT_VER libraries
1.7 libqpepim
2 libqpepim and libqpepim1

Leave QTOPIA_COMPAT_VER blank to use the most recent version available.

Note: While this does not prevent the use of methods introduced in a later release being used in an earlier release, caution is required. If classes or methods from a new release are required for an earlier target device, it is advised to install libqtopia and/or libqtopia2 on the device to obtain the additional functionality.

Translatable Files

The TRANSLATABLES variable holds the list of files that are to be translated. To ease maintenance, it is suggested to include files from all editions into the same .ts files. If conditional directives are added to the .pro file, for example, QTOPIA_PHONE for phone specific files, ensure that the TRANSLATABLES variable continues to contain sources from ALL builds.

It is easiest to create globally-scoped variables to contain all the files as follows:

    SOURCES=main.cpp
    HEADERS=main.h
    PHONE_SOURCES=main_ph.cpp
    PHONE_HEADERS=main_ph.h
    QTOPIA_PHONE {
        SOURCES+=$$PHONE_SOURCES
        HEADERS+=$$PHONE_HEADERS
    }
    TRANSLATABLES+=$$PHONE_SOURCES $$PHONE_HEADERS # Add this now so we don't forget later

    ...

    TRANSLATABLES*=$$HEADERS $$SOURCES # The * avoids duplicates

As well as the code translatables there may also be non-code translatables. For internal projects located in $QPEDIR/src, these files may be handled automatically but be located in standard locations.

This table lists files that are automatically handled for each directory.

directory files
apps .directory *.desktop
plugins .directory *.desktop
i18n .directory *.desktop
etc *.conf *.scheme *.desktop
pics config
services *

The reason these things are combined is that the calls to lupdate must include all the files used to generate the .ts file. Translations for these files are stored in a few global files to help minimise storage and memory requirements.

Internal projects are free to have other non-code translatables. These should be handled in the same way that external projects handle non-code translatables. For example, libqtopia1 does this with time zone data.

External projects require unique names for non-code translatables. For example, the example application uses example-nct.qm for it's non-code translatables. This file must be mentioned in each file. For example, the following code is in example.desktop:

[Translation]
File=example-nct
Context=Example

The .pro file must then tell the build system which non-code files are translatables. This is done with the NON_CODE_TRANSLATABLES variable. For example, the following registers the example.desktop file as a non-code translatable:

NON_CODE_TRANSLATABLES=example.desktop

There is one more step that must be done. The build system must know what .qm files your non-code translatables use. You set the NON_CODE_TRTARGETS variable to indicate this. For example, the following indicates to the build system that example-nct.qm should be created from example-nct-lang.ts:

NON_CODE_TRTARGETS=example-nct


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0