Home · All Classes · Grouped Classes · Annotated · Functions

Guide to Configuring and Building Qtopia

This document is targeted to new users, that is, people who are not familiar with the Qtopia build process. However it will also help those who have used previous Qtopia releases as there are some important changes that you need to be aware of.

Note: This document is not for people using binary packages (eg. demo, SDK).

• Getting Started
• Prepare the External Dependencies
• Prepare the Source Tree
• Prepare the Build Tree
• Create Device-specific Files
• Taming the Configuration Explosion
• Build Steps
• configure
• make
• make install
• Now What?

Getting Started

The first thing you need to do is to ensure you have a suitable source package and any external dependencies. The Getting Started page has the information you require to select a suitable source package. If you require any language packs or third-party additions, ensure you have them also. Refer to Qtopia Internationalization for further information.

This document assumes that packages are downloaded to ~/build/qtopia. You will need to substitute the real location if you are not using this one. This document may also use terms that are confusing so it is advisable to refer to the Terms section of the Qtopia Build System User Guide to avoid confusion.

Prepare the External Dependencies

The Dependencies and Prerequisites document describes the libraries, compilers and other requirements for Qtopia. These need to be provided as part of the base Linux system for your device by your system integrator. Information on how to compile third-party libraries is available in: Compiling 3rd-party Libraries.

Prepare the Source Tree

Your downloaded source package should have a name such as:

    qtopia-phone-commercial-src-4.2.3.tar.gz

The .tar.gz indicates that the file is a gzip-compressed tarball that can be extracted using the command:

    tar zxf <file>

This will provide a directory named qtopia-phone-4.2.3 (for this example). Note that a Qtopia source package is a combination of Qtopia and Qt sources.

Additional packages should be unpacked inside the source tree. For example, to unpack the GB language pack you would do the following:

    $ cd ~/build/qtopia/qtopia-phone-4.2.3
    $ tar zxf ../qtopia-language-en_GB-4.2.3.tar.gz

If you are not sure where a tarball should be unpacked, you can use the command:

        tar ztf

which lists the contents instead of extracting them. The following is an example of what it will display:

    $ tar ztf qtopia-phone-commercial-src-4.2.3.tar.gz
    qtopia-phone-4.2.3/
    qtopia-phone-4.2.3/bin/
    qtopia-phone-4.2.3/bin/at
    qtopia-phone-4.2.3/bin/installhelp
    qtopia-phone-4.2.3/bin/mkpkg
    qtopia-phone-4.2.3/bin/common.pm
    qtopia-phone-4.2.3/bin/targunzip
    qtopia-phone-4.2.3/bin/cache.pm
    qtopia-phone-4.2.3/bin/targzip
    qtopia-phone-4.2.3/bin/installpic
    ...

As you can see, everything will be unpacked to the qtopia-phone-4.2.3 directory. In contrast, the GB language pack:

    $ tar ztf qtopia-language-en_GB-4.2.3.tar.gz
    etc/
    etc/dict/
    etc/dict/en_GB/
    etc/dict/en_GB/common
    etc/dict/en_GB/words
    examples/
    examples/inputmethod/
    examples/inputmethod/popup/
    examples/inputmethod/popup/libpopupim-en_GB.ts
    examples/inputmethod/composing/
    ...

has no qtopia-phone-4.2.3 directory and so you should extract the files from inside the qtopia-phone-4.2.3 directory.

The following sub-directories are found in qtopia-phone-4.2.3:

The following files and scripts are also contained in qtopia-phone-4.2.3:

The rest of this document needs to refer to the source tree and so assumes for ease of use that you have set an environment variable as follows:

    export QTOPIA_DEPOT_PATH=~/build/qtopia/qtopia-phone-4.2.3

Prepare the Build Tree

While it is possible to build in the source tree it is not recommended. If you build in a separate directory you can easily remove the build without deleting the sources. There is even a facility to make it easier when you are changing code. For this example, we will build in a directory called build:

    cd ~/build/qtopia
    mkdir build

The use of the QPEDIR environment variable is optional when only running configure, make or qtopiamake, but it is required to run scripts or perform depot hopping so it is a good idea to set it anyway.

    export QPEDIR=~/build/qtopia/build

Create Device-specific Files

If you are building on a PC you can most likely skip this step. When building for a device, there are a number device-specific files that Qtopia requires and there are two ways to handle them:

• Classic handling
• Device Profile

Classic handling will be familiar to anyone who has built previous versions of Qtopia. The files for your device are spread across the source tree, so it is recommended to group device-specific files into a Device Profiles to make it easier to manage. The documentation also lists the classic files that are replaced so a description of classic files will not be presented here.

Taming the Configuration Explosion

Qtopia has many configuration options and Qtopia Core also has its own set of options. If you are building on a PC you will probably not need to use many of them but they are required when building for a device. Determining which options are required can be difficult.

For convenience, the help output for Qtopia and Qtopia Core has been saved into the documentation. Those pages were generated when the source package was created. If you want to be sure of the available options it is advisable to check the source, the scripts themselves. The following table indicates how to obtain configuration help from the source:

Note: These commands will output copious amounts of information so it is advised to use a pager such as less or more, or even pipe the output into a file for perusal with a text editor using a command such as: configure -help > output.txt.

The following are some common items to set:

• -debug
  • The default is to build in release mode. Building in debug mode allows you to debug your application, however it also results in larger files and you will need to NFS mount the files if you are running on a device.
• -silent
  • Building normally results in a large amount of output because every compile job is printed. Using -silent suppresses the compile job printing and makes it easier to identify build problems. If you have used -silent and you need to see more output you can run make loud. This is not quite the same as building without -silent but it can come in handy when you need to see compiler commandlines.
• -extra-qtopiacore-config
  • This is an important option when building for devices. It is the mechanism by which configure arguments are passed to Qtopia Core. There is a similar option for passing arguments to Qt. For example, configure -extra-qtopiacore-config -system-libjpeg.
• -I <path> and -L <path>
  • If the external dependencies are not located in a location that your compiler searches, you will need these arguments to locate the headers. Typically, it is Qtopia Core that requires them so you will need to wrap them in -extra-qtopiacore-config. For example, configure -extra-qtopiacore-config '-I /path/to/libjpeg/include' -extra-qtopiacore-config '-L /path/libjpeg/lib'.
• -image <path>
  • Allows you to set the install location at configure-time. This path is then used as the default value for the -prefix option.
  • -prefix <path>
  • Specifies the runtime location. The default is the path set by the -image option.
• -R <path>
  • Define a run time search path for shared libraries. For example, you might pass -R /opt/Qtopia/lib -extra-qtopiacore-config '-R /opt/Qtopia/lib' to allow Qtopia to run without an LD_LIBRARY_PATH.
• -device <device>
  • See Device Profiles for details.
• -xplatform <target>
  • This is required when building for devices. It specifies the mkspec to use when building code for the device. A mkspec that is suitable for you may be available, but generally you will require one that is specific to your compiler and device.
• -defaultbuttons <arg>
  • Every device needs a suitable defaultbuttons.conf file. If you don't create a file, one of the default ones will be used. See Keypad Button Behavior for information about defaultbuttons.conf.
• -singleexec
  • If your device does not need installable applications, enabling single-exec buiding is a great way to improve application startup times. See Qtopia Single Exec for mode information about single-exec building.
• -displaysize <WxH>
  • It is a good idea to specify the screen size as theme backgrounds are scaled to this size and some images are included or excluded based on the screen size.
• -dislayrot <angles>
  • To reduce the size of your image, you can skip installing fonts for additional rotations by specifying displayrot 0. You should also remove settings/rotation from the build if you do this.

Build Steps

configure

configure is run once the correct arguments to use have been determined. A common problem at this stage is that your compiler is not set up correctly and configure dies indicating that your compiler is broken. You can run configure -verbose to obtain detailed information about the test. A common cause is that the compiler is not in the path. If you have a device profile, add the compiler bin directory to the path in the environment file, otherwise you will have to remember to do it manually before running configure.

Note that configure should be run from the build directory. For example:

    cd $QPEDIR
    $QTOPIA_DEPOT_PATH/configure [options]

make

Once Qtopia is configured, building is just a matter of running make. It is possible that you will receive compile errors if you are not using a GCC-based compiler. If this happens you'll need to modify the code to work with your compiler or try another compiler.

Note: make cannot be run from within the <source_tree>/qtopiacore or <build_tree>/qtopiacore directories. Qtopia manages these directories and when running make manually, environment variables may not be set correctly resulting in incorrect directories being used for the build.

make install

make install does not really install Qtopia, it sets up the image directory. This directory contains everything required to run Qtopia (except for external dependencies).

If you have used previous versions of Qtopia, the handling of -image and -prefix may seem strange. Please refer to Changes for 4.2.0 for an overview of how these parameters are handled in Qtopia 4.2.

Now What?

For information about running Qtopia refer to Running Qtopia.