|
Qtopia Home · Home · Reference · User Guide · Internals | |
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.
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.
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.
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.
Set the path to the toolchain such that $TOOLCHAIN/bin contains the compiler binaries. The build system will add $TOOLCHAIN/bin to your PATH if it is not already there. If this variable is not set, none of the following variables will have any effect and your PATH will not be modified.
Set to 1 to enable teambuilder support (if teambuilder can be found). The user should export TBDIR if they have not installed teambuilder into /opt/teambuilder. If this is not set (or set to 0) teambulider support will be disabled and none of the following variables will have any effect.
Set the prefix your compiler uses. For example, if your compiler is called arm-linux-gcc the prefix is arm-linux-.
Set to auto to ask the compiler or specify an explicit version. You might want to set an explicit version if you have multiple, compatible compilers available. For example, 4.1.*.
Specify the TEAMBUILDER_SYSTEM value your toolchain requires. If this is set a set of wrapper scripts will be created so that the variable is set correctly. If you do not set this variable wrapper scripts will not be used.
Specify the compiler names your toolchain has. The default ("gcc g++") is probably acceptable though some toolchains might require "cc c++" instead. The mkspec for the device will contain the compiler names.
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
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.
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.
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.
Configuration tweaks can be done here. This is read just after the configure-generated config.pri, before each .pro file is read.
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.
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
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.
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!).
See Document Storage for information about Storage.conf.
This directory is used to provide device-specific help file overrides. It can only be used to override files in <source>/help.
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.
Like features but for Qt/Qtopia Core projects. The Greenphone device has an example of how to use this directory.
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.
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
The camera will disable it's built-in drivers if camera/*.cpp exists. It also pulls in camera/*.h.
To support HSAG(HFP) and HSP Bluetooth Profile QAudioStatePlugin must be supplied in src/plugins/audiohardware/<devicename>
Device profiles do not currently help you with the following items.
See also Overviews.
| Copyright © 2008 Nokia | Qtopia Build System Documentation |