Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded

Building Qtopia from Source

This document should be read inconjunction with Getting Started which explains the process of downloading and installing Qtopia. It assumes that you have already gathered the necessary files and are ready to build Qtopia from the source code.

If you have installed Qtopia using an rpm then you cannot compile Qtopia yourself. Please proceed to Running Qtopia or go to the "Building and Compiling" section in the reference documentation which tells you more about building and compiling your own Qtopia applications.

To actually build Qtopia yourself you will need the software packages as described in the "Install procedures" section. If you haven't installed all the packages yet, then please go through that section before proceeding.

If you have installed all the packages and have set the environment variables: TMAKEDIR, QT2DIR, QT3DIR, QTEDIR and QPEDIR then you are ready to build Qtopia.

Note: Qt/X11 2.3.2 will attempt to locate and use the freetype 1.x library for font smoothing (freetype 2.x is a different thing that doesn't work with Qt/X11 2.3.2). Unfortunately this can happen even if you don't have the freetype development library and headers installed. Either install the freetype-devel package or configure with -no-xft.

Acceptable directory characters

There are some limits to the acceptable characters in directories. The details are in the Build Environment document.

The Easy Way

For your convenience we have provided a build script in the $QPEDIR/scripts subdirectory. Please understand that this script is just a starting point and may require some tweaking for your specific situation. We have also filled the script with lots of comments and added extra debugging output lines.

To run the script simply do the following:

    $QPEDIR/scripts/build_qtopia

Depending on your package type this will build you a Qtopia Phone, a Qtopia PDA, or a Qtopia Core version.

In the event of trouble you may want to get in touch with us for help in resolving the issue. If that happens please pipe the output of the script into a file and send us that file together with the script that you actually used and any additional comments. This way we can solve your problem much faster and much more efficiently. To log the script output into a file do the following:

    $QPEDIR/scripts/build_qtopia > log.txt 2>&1

The Hard Way

Although the script is nice for starters it is sometimes not enough, or maybe you just want to do it all by yourself. If so, then here are the instructions:

Build Qt 3.3 + tools
To build Qt 3.3 and the tools you must do the following:

    cd $QT3DIR
    export QTDIR=$QT3DIR
    export PATH=$QTDIR/bin:$PATH
    export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
    echo yes | ./configure -fast -thread
    make sub-src
    cd tools/linguist/lrelease
    make
    cd ../lupdate
    make
    cd ../../designer/uilib
    make
    cd ../uic
    make

Build Qt 2.3.2
To build Qt 2.3.2 you must do the following:

    cd $QT2DIR
    export TMAKEPATH=$TMAKEDIR/lib/linux-g++
    export QTDIR=$QT2DIR
    export PATH=$QTDIR/bin:$PATH
    export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
    ./configure -no-xft
    make
    mkdir $QTEDIR/bin
    cp bin/uic $QTEDIR/bin/

Build QVfb
In this step we build and link the qvfb sources from Qt 2.3.9 against the static Qt library from Qt 2.3.2.

    export TMAKEPATH=$TMAKEDIR/lib/linux-g++
    export QTDIR=$QT2DIR
    export PATH=$QTDIR/bin:$PATH
    export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
    cd $QTEDIR/tools/qvfb
    tmake -o Makefile qvfb.pro
    make
    mv qvfb $QTEDIR/bin/

Build Qt/Embedded
To build Qt/Embedded you must do the following:
```
    cd $QTEDIR
    export TMAKEPATH=$TMAKEDIR/lib/qws/linux-x86-g++
    export QTDIR=$QTEDIR
    export PATH=$QTDIR/bin:$PATH
    export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
    cp $QPEDIR/src/qt/qconfig-qpe.h src/tools/
    ./configure -system-jpeg -no-xft -qconfig qpe -keypad-mode -qvfb -depths 4,8,16,32 [extra options: see below]
    make sub-src
```
Warning: To build Qtopia the jpeg library and header files to suit the target system MUST be provided by your compiler tool chain or your system.
Extra options:
- The configure option -keypad-mode, which enables keypad widget navigation support, is required when building the Qtopia for a phone device, but it should not be used for a PDA build of Qtopia.
- You may want to use the configure option -gif for gif support.
- Run the command :
```
         ./configure --help
    
```
  for additional configure options

Build Qtopia
To build Qtopia phone you must do the following:

    cd $QPEDIR
    export QTDIR=$QTEDIR
    export PATH=$QPEDIR/bin:$PATH
    ./configure -edition phone -no-qtopiadesktop -dqt $QT3DIR
    make
    make install

To make the PDA version you must do the following:

    cd $QPEDIR
    export QTDIR=$QTEDIR
    export PATH=$QPEDIR/bin:$PATH
    ./configure -edition pda -no-qtopiadesktop -dqt $QT3DIR
    make
    make install

Compiling Qtopia for the Device

This process is very similar to the steps taken for building Qtopia for the X11 capable host, the major difference is the arguments to configure. It is recommended, but not required, that fresh copies of Qtopia and Qt/Embedded be extracted to a location such as ~/dev/arm.

See System Integrators' Guide for additional details on creating a configuration files for a new device.

Re-using previous packages
Qt 2.3.2, Qt 3.3 and tmake built/installed in the previous steps can be re-used. You will need to ensure that
- TMAKEDIR : points to the Tmake tool used for building Qt-Embedded
- QT2DIR : points to the Qt-X11 2.3.2 directory
- QT3DIR : points to the Qt-X11 3.3 directory
- QTEDIR : points to the Qt-Embedded 2.3.9 directory
- QPEDIR : points to the Qtopia source directory

Copy libqt and uic
To re-use libqt.so.2.3.2 and uic you must :

    cp $QT2DIR\lib\libqt.so* $QTEDIR\lib\
    mkdir $QTEDIR\bin\
    cp $QT2DIR\bin\uic $QTEDIR\bin\

Build Qt/Embedded for the device
To build Qt/Embedded for an arm device you must do the following:
```
    cd $QTEDIR
    export TMAKEPATH=$TMAKEDIR/lib/qws/linux-arm-g++
    export QTDIR=$QTEDIR
    export PATH=$QTDIR/bin:$PATH
    export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
    cp $QPEDIR/src/qt/qconfig-qpe.h src/tools/
    ./configure -xplatform linux-arm-g++ -system-jpeg -no-xft -qconfig qpe -keypad-mode -no-qvfb -depths 4,8,16,32 [extra options: see below]
    make sub-src
```
Warning: To build Qtopia the jpeg library and header files to suit the target system MUST be provided by your compiler tool chain or your system.
Extra options:
- See $QTEDIR/PLATFORMS for a complete list of platforms that can be passed to the -xplatform option
- The configure option -keypad-mode, which enables keypad widget navigation support, is required when building the Qtopia for a phone device, but it should not be used for a PDA build of Qtopia.
- You may want to use the configure option -gif for gif support.
- Run the command :
```
         ./configure --help
    
```
  for additional configure options

Build Qtopia for the device
To build Qtopia phone you must do the following:

    cd $QPEDIR
    export QTDIR=$QTEDIR
    export PATH=$QPEDIR/bin:$PATH
    ./configure -xplatform linux-arm-g++ -edition phone -no-qtopiadesktop -dqt $QT3DIR
    make
    make install

To make the PDA version you must do the following:

    cd $QPEDIR
    export QTDIR=$QTEDIR
    export PATH=$QPEDIR/bin:$PATH
    ./configure -xplatform linux-arm-g++ -edition pda -no-qtopiadesktop -dqt $QT3DIR
    make
    make install

Build Qtopia packages the device
```
    cd $QPEDIR
    make packages
```

Now what?

After running the script or building Qtopia manually you should have a set of Qtopia binaries and be ready to run them. The binaries are put into places like $QPEDIR/bin, $QPEDIR/lib and $QPEDIR/plugins but these are not the ones you should install onto a device. In order to make integrating Qtopia on a device easier we have provided an image directory that contains all the files (and only those files) that should be installed onto the device. This image directory is located at $QPEDIR/image/opt/Qtopia and if you cd into it you'll see a bin dir, a lib dir and so on.

IMPORTANT: Depending on the device you are installing Qtopia on you may or may not need the additional libraries libjpeg and libc. For backward compatibility reasons we have provided these libraries in the arm/lib directory. If you run Qtopia on your device and you get error messages referring to one of these libraries then please move them to a different location and ensure that you have the correct version of these libraries on your device.

For information about running Qtopia please go to Running Qtopia

Troubleshooting

If a Qt/Embedded application does not appear inside QVfb then try removing the old Qt/Embedded temporary data. For example:
```
    killall qpe quicklauncher qvfb
    rm -rf "/tmp/qtembedded-$LOGNAME/"
    rm -rf /tmp/qtembedded-0/
    
```
If you are intending to connect your Qt/Embedded application to QVFb you must not configure Qt/E-2.3.9 with the -no-qvfb command.
If you are experiencing trouble with your Qtopia image then do a clean install of Qtopia via:
```
    cd $QPEDIR
    make installclean
```
and try running your application again.

Trademarks

Qtopia version 4.0.0