![]() Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference |
![]() |
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.
There are some limitations to the acceptable characters in directories, please refer to the Acceptable Directory Characters section of the Build Environment document.
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 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 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. |
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>
When adding a core library (ie. a library that other Qtopia libraries depend on), additional steps are required as follows:
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,
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:
|
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:
|
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. |
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.
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 makefiles contain a number of Qtopia extensions which facilitate the following behavior:
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
make qmakefrom a sub-directory target causes all sub-projects to be re-processed, however this can be avoided by running
make regenerate
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:
cd /path/to/qtopia/sources QPEDIR=$PWD ./configure -setupdepothop
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 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.
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 |
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. |
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.
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
|