Qtopia Home · Home · Reference · User Guide · Internals

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.

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).

    -edition phone -xplatform mydev -arch arm -no-qvfb
    -release -displaysize 240x320 -quicklaunch
    -defaultbuttons phone
    -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

Another common variable to put in the environment file is PKG_CONFIG_PATH. It lets pkg-config find the packages you have in your toolchain. A cursory examination of toolchains reveals that .pc files typically have incorrect prefix values so you should also set the PKG_CONFIG_PREFIX variable to override the prefix. Note that these variables must be exported.

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

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 Qtopia Core. 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 Qtopia Core and Qtopia.

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.

defaultbuttons.conf

Every device needs a suitable defaultbuttons.conf. Use of this file only happens if -defaultbuttons is not passed to configure. See Keypad Button Behavior for a description of defaultbuttons.conf.

config.pri

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

projects.pri

This is for enabling and disabling projects as appropriate for the device. This is processed after general.pri and commercial.pri but before custom.pri and local.pri so that the user can still override the projects.

If you want to heavily customize the project list it may be easier to build the list from scratch instead of removing things from the list. To do this, set the no_general_pri CONFIG value in config.pri, add whatever projects you want in projects.pri and ensure you have a custom.pri file so that the default one is not used. The suggested way to select projects is to copy general.pri and modify to suit your device.

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 added as a project tree (ie. configure -build <source>/devices/foo/src). It is recommended to mimic the Qtopia source tree layout for ease of reference. See Project Trees for information about project trees.

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!).

Storage.conf

See Document Storage for information about Storage.conf.

help

This directory is used to provide device-specific help file overrides. It can only be used to override files in <source>/help.

features

This directory is searched for features before any other directory. Device-specific overrides of features can be placed here. The Greenphone device has an example of how to use this directory.

features/qt_patch

Like features but for Qt/Qtopia Core projects. The Greenphone device has an example of how to use this directory.

override/addition directories

There are a number of projects in Qtopia that use files from the device profile in preference to or in addition to other files.

A number of files can be placed into a device profile to override the original one.

Server Customization

The server will use server/scomisc.cpp instead of it's own bluetooth/scomisc/scomisc.cpp. It will also include server/*.ui, server/*.h and server/*.cpp. See also Qtopia Server Widgets

Device Supplied Camera Plugin

The camera will disable it's built-in drivers if camera/*.cpp exists. It also pulls in camera/*.h.

Device Supplied Bluetooth Audio State Plugin

To support HSAG(HFP) and HSP Bluetooth Profile QAudioStatePlugin must be supplied in src/plugins/audiohardware/<devicename>

Limitations

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

See also Overviews.


Copyright © 2008 Nokia Qtopia Build System Documentation