Qt Extended Home · Build System Home · Reference · User Guide · Internals codeless banner

Device Profiles

Device profiles are a way to minimize the hassle of configuring for a device. A single directory contains all of the configuration information necessary to build for the device.

Profiles live in the devices directory in the source tree. They are activated by running configure -device foo.

There are a number of features. They are described by the file that implements them.

configure

The single most annoying thing about compiling for a new device is that usually lots of configure arguments are required. These must be communicated to anyone wanting to compile for the device. A device profile can have a file named configure that specifies configure arguments.

Actually there are 3 files for this but only configure is required.

A desktop build is obtained by running configure -device foo -qvfb. Note that this will not work unless the configure-qvfb file exists.

When you run configure [args1] -device foo [args2] configure checks for <source>/devices/foo/configure and if it's found, configure re-launches itself with -device foo replaced by the contents of the file.

Here's a sample configure file (note that whitespace is interpreted by the shell so the newlines are not relevant).

    # lines beginning with # are ignored
    -edition phone -xplatform mydev -arch arm -no-qvfb
    -release -displaysize 240x320 -quicklaunch
    -prefix /opt/Qtopia

The ordering of arguments is significant. Anything specified before -device can be overridden by the device profile while anything after -device can override the device profile.

For example, the sample file above specifies -release. Here's what would happen if you passed -debug before and after -device foo.

environment

This script (if it exists) is sourced before re-running configure and before Makefile calls Makefile.target. The suggested use is to setup paths to an appropriate toolchain. The DEVICE_CONFIG_PATH variable is set to the path of the device profile so that you can locate files inside the device directory.

toolchain

In order to reduce duplicated code the recommended use of this file is as follows:

    #!/bin/sh
    TOOLCHAIN=/path/to/mips/cross/compiler
    USE_TB=1
    TB_CC_PREFIX=mips-linux-
    TB_CC_VER=auto
    TB_SYS=mips:system

The following variables are recognised by the build system.

pkg-config

There are variables you can set related to pkg-config. If you do not set these values pkg-config will not be used. PKG_CONFIG_PATH must point to the location where your toolchain's .pc files are. PKG_CONFIG_PREFIX must point to the location where your toolchain's libs are installed. Note that these variables must be exported.

    export PKG_CONFIG_PREFIX=$TOOLCHAIN/mips-linux
    export PKG_CONFIG_PATH=$PKG_CONFIG_PREFIX/lib/pkgconfig

See also the pkg-config overview.

mkspecs

Since a typical behavior of the configure file is to set -xplatform it is useful to have a platform spec for the device. Device profiles can contain a mkspecs directory that is checked for -platform and -xplatform spec files. This is so that you do not have to modify the Qt depot in order to ensure your device can be built (though it is possible to move a spec file to Qt without having to modify the configure line).

For example, the mydev spec files are in it's configuration directory.

    devices/mydev/mkspecs/qws/linux-mydev-g++/qmake.conf
    devices/mydev/mkspecs/qws/linux-mydev-g++/qplatformdefs.h

There are mkspecs that ship with Qt for Embedded Linux. They are in qtopiacore/qt/mkspecs/qws. You should copy one that is similar to your device (eg. linux-arm-g++) and modify it to suit. Things to check are the name of the compiler, the compiler flags (especially optimization flags). You may also want the mkspec to specify a define that you can use to enable device-specific code in Qt for Embedded Linux and Qt Extended.

It is customary to define only what you need in qmake.conf and to include some common files. To do this you will need to use the MKSPECS environment variable. Here is an example of how to use this variable.

    MKSPECS=$$(MKSPECS)
    isEmpty(MKSPECS):error(MKSPECS was not set!)
    exists($$MKSPECS/common/linux.conf):include($$MKSPECS/common/linux.conf)
    else:error($$MKSPECS/common/linux.conf does not exist!)

This grabs the environment variable to a local variable. It then asserts that it was set and includes one of the common files. If the file cannot be found it asserts.

custom.h/custom.cpp

Since these files are tied to a device it is useful to have them in the device profile. If these files are not present configure will look in the traditional location, <source>/src/libraries/qtopia/custom-<xplatform>.(h|cpp). See <custom.h> for more information about these files.

For reference implementations of these files, the existing files found in <source>/devices/<device>/custom.* and <source>/src/libraries/qtopiabase/custom-<xplatform>.* may be of assistance.

config.pri

Configuration tweaks can be done here. This is read just after the configure-generated config.pri, before each qbuild.pro file is read.

projects.pri

This is for enabling and disabling projects as appropriate for the device. This is processed after the module includes (module_*.pri) but before custom.pri and local.pri so that the user can still override the projects.

custom.pri

If present, this file overrides <source>/src/custom.pri. It can include the contents of that file by using the following command.

    include($$QTOPIA_DEPOT_PATH/src/custom.pri)
    # disable one of the custom projects
    PROJECTS-=applications/customapp

src

If the src directory exists, it is mapped to /src in the solution filesystem. Files in this directory will override files in the source tree.

qconfig.h

This file overrides the use of qconfig-qpe.h. It can define all it's own things or it can #include "qconfig-qpe.h" and override settings (watch out for dependencies if you do this though!).

help

This directory is used to provide device-specific help file overrides.

Limitations

Device profiles do not currently help you with the following items.

See also Overviews.


Copyright © 2009 Trolltech
Qt Extended - Build System Documentation