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

# Building Qtopia from Source

- - Acceptable directory characters
  - The Easy Way
  - The Hard Way
  - Compiling Qtopia for the Device
  - Now what?
  - Touchscreen Phone Calibration
  - Troubleshooting

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.

If you have access to the Qtopia Tools package then you do not need to build either Qt/X11-2.x or Qt/X-3.3.x and can skip to the Build Qt/Embedded section.

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, DQTDIR, 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 $DQTDIR
          export QTDIR=$DQTDIR
          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.10 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

  If you are using the Qtopia Tools package then first

          export LD_LIBRARY_PATH=$QT2DIR/lib:$LD_LIBRARY_PATH
          cp $QT2DIR/bin/qvfb $QTEDIR/bin/
          cp $QT2DIR/bin/uic $QTEDIR/bin/

  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
          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
          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 customization qtopia to suit 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
  - DQTDIR : points to the Qt-X11 3.3 directory
  - QTEDIR : points to the Qt-Embedded 2.3.10 directory
  - QPEDIR : points to the Qtopia source directory

- Copy uic
  If you are using the Qtopia Tools package then :

          mkdir $QTEDIR/bin/
          cp $QT2DIR/bin/uic $QTEDIR/bin/

  other wise :

          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 uuid and jpeg library/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
          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
          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

### Touchscreen Phone Calibration

If you are building Qtopia Phone edition for a touchscreen device, you will need to calibrate the touchscreen manually as Calibration is not run automatically. With Qtopia Phone running, enter the following command to start Calibration.

    qcop "QPE/System" "execute(QString)" "calibrate"

This outputs calibration information to the $HOME/Settings/pointercal file which you should copy to /etc/ so you won't have to repeat this process.

NOTE : You must have QPE_NEED_CALIBRATION defined in your custom-<platform-spec>.h file. See also Qtopia - Customizing Qtopia for a Device .

### 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.10 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.