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

Building Qtopia from Source

Introduction

This document should be read after Getting Started which explains the process of selecting and downloading a Qtopia source package. It is assumed that you have read the section on the Tools available in the package to help build and develop Qtopia and Qtopia-based applications.

It is further assumed that the necessary source packages have been downloaded and you are ready to build Qtopia from the source code.

Note: If you have downloaded an RPM package such as a qtopia-phone-developer-sdk-suse82.i386.rpm then you need to read the Installing an RPM section and then proceed to Running Qtopia or to the Building and Compiling section in the reference documentation for further information on building and compiling Qtopia applications from RPM packages.

Installing the Source Package

For Qtopia 2.2.0 and later, any Qtopia source package is a combination of Qtopia, Qt and tmake sources.

Qtopia packages can be installed anywhere, as long as the user has read/write access to the directories. There are some limits to the acceptable characters in directories however; spaces and characters that can be interpreted as a regular expression (regexp) are not allowed. For more details see the Acceptable Directory Characters section of the Build Environment document.

To install the package, cd into the directory in which the package should be installed and then use the following command:

   tar -xzf mypackage (where 'mypackage' is the name of the package to be installed)

After execution of the tar command a sub-directory is created that forms the root directory of the Qtopia source package. For the various Qtopia products the product base directory name will be as follows:

Product Directory Name
Qtopia PDA Edition qtopia-pda-2.2.0
Qtopia Phone Edition qtopia-phone-2.2.0
Qtopia Core Edition qtopia-core-2.2.0

For the rest of this documentation it is assumed that the package was unpacked in ~/build and that the unpacked package was a phone source package, that is, there will now be a ~/build/qtopia-phone-2.2.0 directory. This directory will be referred to as qtopia_root_dir.

The following sub-directories are within qtopia_root_dir:

Sub-directory Description
qtopia Contains all qtopia source code.
qt2 Contains the Qt 2.3.x source code that compiles for both X11 and embedded configurations.
dqt Contains Qt-x11-3.3.x sources. Qt-x11-3.x is used to build certain tools such as Assistant and Linguist as well as providing a Qt for Qtopia Desktop to build against.
tmake Contains tmake-1.14 sources. tmake is a tool that is used to configure Qt 2.3.x

The following files and scripts are also contained in qtopia_root_dir:

File/Script Description
LICENSE The official license text that is applicable to the package. Note: The LICENSE file will not be available until the configure command has been executed at least once.
LODI A List Of Deliverable Items, that is, a list of all files that can be found in the package.
README.html A basic introduction that guides the user to the help documentation.
configure The script that must be used to configure Qtopia.
Makefile.in A template Makefile, used by the configure script to create a real Makefile.

How to Build Qtopia

To build Qtopia, cd into qtopia_root_dir and use the commands:

    ./configure
    make
    make install
That's it!

There is obviously more to tell, so the next sections go into a little more detail.

Building Qtopia Tools

To build Qtopia a number of Qtopia Tools need to be available. Some of these tools such as moc, uic and qmake are part of any Qt package and are included in the Qtopia source package.

Note: The building of the tools is completely automatic and in most cases the following guidelines can be ignored.

Whenever configure is called from qtopia_root_dir the tools are configured and calling make or make tools will build the tools if required. The default configurations that are used for the Qt-x11-2.3.x and Qt-x11-3.3.x versions should work for most machines, but in exceptional cases the configuration may be modified by specifying a configuration explicitly on the command line. For example, the following configuration for qt2:

    ./configure -qt2 "-opengl -no-xft -no-sm"
will override the default configuration for building Qt-x11-2.3.x.

The tools need to be built only once. If Qtopia is built with a different configuration the tools remain the same and it is not necessary to recompile them. In fact, it may very well be the case that if you install an upgrade of Qtopia it still won't be necessary to re-build the tools. So in order to make the build process as efficient as possible the tools can be cached into a hidden directory in the directory $HOME and the -cache command line option provided to the script configure activates this mechanism.

When Qtopia is built for the first time and the -cache option is used, the build script looks for the directory $HOME/.qtopia-*-cache. If it does not exist the tools are built and copied into the cache directory. For any successive builds of Qtopia the tools are re-used from the cache, saving considerable time.

Whenever it is necessary to fully re-build the tools it is sufficient to call:

     make cleantools 
     make tools  

Note: Qt/X11 2.3.x will attempt to locate and use the freetype 1.x library for font smoothing (freetype 2.x is a different library that does not work with Qti/X11 2.3.x). Unfortunately this can happen even if the freetype development library and headers are not installed. The default configuration of Qt-x11-2.3.x has freetype fonts disabled by using the option -no-xft. This only affects the visual appearance of designer.

Building Qtopia

As previously stated, Qtopia is built using:

    ./configure
    make 
    make install 

The configure script can build all configurations of Qt/Embedded and Qtopia with additional configuration options controlled via command-line options to the configure script.

For a full overview of all possible options use the following command:

  ./configure -help

The configure process is divided into a number of configure scripts; one for each sub-product in the package. That is, there is a qtopia/configure, a qt2/configure and a dqt/configure. Each of these configure commands provide additional help information for the specific sub-product. To obtain help for a specific sub-product use the option -help on the command line of the top-level configure described above.

In some cases the configure scripts for the sub-products need additional information to provide the best possible help information. This information is provided by setting environment variables using:

   . ./config.cache

Note: The "dot space dot" is not a typo but instructs the command shell to load the contents of the script into the current environment.

Additional configuration information for the various sub-products can be found by typing:

sub-product command
Qtopia qtopia/configure -help
Qt 2.3.x qt2/configure -help
Qt 3.3.x dqt/configure -help

Note: config.cache only exists if the top level configure has run at least once. If the cache does not exist run the ./configure command, then read all the help from the configure scripts to decide the options to be used in the configure call.

Re-building parts of Qtopia

Parts of Qtopia can be re-built by specifying the target in the make command as follows:

    cd qtopia_root_dir
    make qpe         to build the Qtopia part only
    make qte         to build the Qt/Embedded part only

Note: Both of these targets will cause the tools to be built if they do not already exist.

Although we encourage building Qtopia from the qtopia_root_dir using configure and make, it is also possible to cd into a source directory and re-build only a section of the product.

For convenience a script for each sub-product, that is, qtopia, qt2 and dqt, is made available that can be sourced to set all environment variables. For example, to set all environment variables that are required to build Qtopia:

  cd qtopia_root_dir
  . ./setQpeEnv

All environment variables are now set and you can manually run the Qtopia configure or make or make part of Qtopia.

Note: The set***Env scripts are found in the qtopia_root_dir and are generated by configure. If the scripts do not exist, please run ./configure to generate the files.

Configuring for a Device

The default Qtopia configuration is to build for an x86 target with defaults provided for an ARM target. If you need to configure Qtopia for your device at some stage, please refer to the following links for further information:

Link Description
Specification Files details setting up specification files for the target device.
Prerequisites details the prerequisites for running Qtopia.
System Customization details how to customize many aspects of Qtopia.
Other Environments details the runtime and time environments.
Build System details Qtopia's qmake-based build system.

Now What?

Once Qtopia is built you will have a set of Qtopia binaries that are ready to run! The binaries are located in directories such as:

However, these are not the directories to be installed onto a device. In order to make integrating Qtopia on a device easier an image directory is provided containing all the files (and only those files) that should be installed onto the device.

This image directory is, by default, located at $QPEDIR/image/opt/Qtopia and contains all the required directories.

For information on changing the image directory prefix dir refer to the compiler help using:

    qtopia/configure -help

Note: Depending on the installation device, the following additional libraries may be required:

For backwards compatibility these libraries are provided in the arm/lib directory. More information about this can be found in the Prerequisites section of the documentation.

If an error referring to one of these libraries occurs when running Qtopia, please move the libraries to a different location and ensure that the correct version of the libraries is installed on your device.

For further information about running Qtopia refer to Running Qtopia.


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0