Qt Toolkit - Installing Qt/Embedded

| Classes - Annotated - Tree - Functions - Home - Structure Qte

# Installing Qt/Embedded

This installation procedure is written for Linux. It may need to be modified for other platforms.

## Required packages

To install and build Qt/Embedded you need several packages. These packages are:

     Qt/Embedded 2.3.10 (or higher, but always a 2.3 version) Qt 2.3.2 for X11 (for emulated desktop development)
    tmake 1.13 (or higher)

Packages for the United States have a different license file. These packages have a "-us" somewhere in the filename, so please use that file instead if it is appropriate to your circumstances. Once installed the package will be in exactly the same place as the "rest of the world" package, it is only the LICENSE file that is different.

In this document we will assume that you have downloaded all packages into ~/dev and are using that as the base directory for the installation and build processes.

## Install the packages

In this step the required packages are extracted onto your computer and the several enviroment variables are initialized.

### Install TMake

TMake is used for building Qt/Embedded

    cd ~/dev
    tar -xzf tmake-1.13.tar.gz
    export TMAKEDIR=$PWD/tmake-1.13

### Install Qt 2.3.2

Qt 2.3.2 is required to build tools such as qvfb that are used to simulate an embedded device on your desktop machine. This library is NOT used on the embedded device.

    cd ~/dev
    tar -xzf qt-x11-2.3.2-commercial.tar.gz
    export QT2DIR=$PWD/qt-2.3.2

### Install Qt/Embedded

We assume you have the commercial Qt/Embedded package. If you use the free package you should adjust the filenames accordingly.

    cd ~/dev
    tar -xzf qt-embedded-2.3.10-commercial.tar.gz
    export QTEDIR=$PWD/qt-2.3.10

You should now have installed all required packages. As long as you have set the environment variables for the other packages correctly you need not worry about them.

IMPORTANT: After you have installed all packages you should have a set of environment variables that point to each and every package that you installed. These environment variables are crucial for building Qt/Embedded, so please verify that they are all correct. You should have the following environment variables set:

    TMAKEDIR : points to the Tmake tool used for building Qt-Embedded
    QT2DIR : points to the Qt-X11 2.3.2 directory
    QTEDIR : points to the Qt-Embedded 2.3.10 directory

After you have installed all packages you no longer need the tar files. These files can be deleted or kept them somewhere safe just in case you decide to reinstall everything from scratch.

## Compiling Qt/Embedded

### 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/Embedded 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

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
    ./configure -no-xft -qvfb -depths 4,8,16,32 [extra options: see below]
    make

Extra options:

You may also want to use the configure options -system-jpeg and -gif for jpeg and gif support.

The configuration system is designed to allow platform-specific options to be added, but in general all Linux system which have framebuffer support can use the "linux-generic-g++" platform.

For help on the additional configure options run ./configure with --help .

### Enable Linux framebuffer support

For application development, we recommend that you use the Qt/Embedded virtual framebuffer. But to actually put Qt/Embedded on a device running Linux, you need to ensure that the Linux kernel has framebuffer support.

You may need to recompile your kernel to enable the framebuffer.

Handheld devices running Linux, such as the SL-5000D and the iPAQ, and most other embedded Linux systems that have a graphical display will already have a framebuffer.

This document does not describe how to do this; the HOWTO-Framebuffer page contains a short description. (You should see a penguin logo at boot time when the frame buffer is enabled.)

- For Matrox G100/G200/G400, use the matrox frame buffer driver.
- For NVidia TNT cards, use the nvidia frame buffer driver.
- For SciTech Snap cards, use the snap frame buffer driver. For Snap product details see http://www.scitechsoft.com/
- For using a transformed frame buffer, use the transformed frame buffer driver.
- For Mach64 and most other cards, use the vesafb driver.
- For Mach64 and most other cards, use the vesafb driver.
- For VGA-compatible cards that are not VESA 2.0 compliant, use the VGA16 driver.

The frame buffer may also need a boot parameter to be enabled. See `/usr/src/linux/Documentation/fb` for details.

The `fbset` program, which is included in most Linux/x86 distributions, may be used to switch video modes without rebooting the system. The video mode active when the server is started will be used. Note: `fbset` does not work with the vesafb driver.

### Runing the launcher demo

To run the laucher demo in a real framebuffer:

    cd $QTEDIR/examples/launcher
    ./start_demo

To run the launcher demo in a virtual framebuffer :

    cd $QTEDIR/examples/launcher
    export QTDIR=$QTEDIR
    export PATH=$QTEDIR/bin:$PATH
    export LD_LIBRARY_PATH=$QTEDIR/lib:$QT2DIR/lib:$LD_LIBRARY_PATH
    qvfb -width 640 -height 480 &
    sleep 10
    ./launcher -qws

### Creating support for a new device

It is recommended that a new configration be created for new a target device. It is through configuration files that compilation tools to use and compilation directives are specified. Typically this involves:

- Identifying the existing suported platform that closest matches your device
- Copying the existing configuration files to a new platform name
- Customizing the newly created configuation files

For example to create a linux-myarm-g++ configuration that uses shared libraries firstly:

    cp -r $TMAKEDIR/lib/qws/linux-arm-g++ $TMAKEDIR/lib/qws/linux-myarm-g++
    cp -r $QTEDIR/configs/linux-arm-g++-shared $QTEDIR/configs/linux-myarm-g++-shared

Then edit $TMAKEDIR/lib/qws/linux-myarm-g++ and $QTEDIR/configs/linux-myarm-g++-shared choosing the compiler, linker and changing the compilation directives as needed.

### Building Qt/Embedded for the device

To build Qt/Embedded for a device, for example linux-myarm-g++ , you must do the following:

    cd $QTEDIR
    export TMAKEPATH=$TMAKEDIR/lib/qws/linux-myarm-g++
    export QTDIR=$QTEDIR
    export PATH=$QTDIR/bin:$PATH
    export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
    ./configure -xplatform linux-myarm-g++ -no-xft -no-qvfb -depths 4,8,16,32 [extra options: see below]
    make

Extra options:

You may also want to use the configure options -system-jpeg and -gif for jpeg and gif support.

For help on the additional configure options run ./configure with --help

### Troubleshooting

- Compilation errors refering to freetype/freetype.h:

  The most likely cause is that the feature configuration type selected has freetype enabled. Reconfigure Qt/Embeddeed selecting a smaller feature configration type, for example "large".

- If launcher application does not appear inside QVfb then try removing the old Qt/E temporary data. eg:

      killall qvfb
      rm -rf "/tmp/qtembedded-$LOGNAME/"
      rm -rf /tmp/qtembedded-0/

- Unable to connect to mouse:

  To kill gpm, run the following command as root:

       gpm -k

- Applications do not run on real framebuffer:

  In some cases, if the server does not work, it will work when run as root. If this happens, there are permissions problems with your filesystem (eg. /dev/fb0 is not writeable by you).

  Show processes using the framebuffer:

       fuser -v /dev/fb0

  Kill such processes:

       fuser -vk /dev/fb0

  or harsher:

       fuser -k -KILL /dev/fb0

- Show existing semaphores:

       ipcs

  Remove semaphores:

       ipcrm

  The communication between client and QWS server for QWS ID, eg 0, is done through the socket `/tmp/qtembedded-0/.QtEmbedded-0`; sometimes it may need to be deleted. (eg. if you run Qt/Embedded as root then later as an unprivileged user).

### Change permissions

To run Qt/Embedded, you need write access to the framebuffer device `/dev/fb0`.

You also need read access to the mouse device. (Note that `/dev/mouse` is normally a symbolic link; the actual mouse device must be readable.)

### Customization

The Qt/Embedded library can be reduced in size by removing unneeded features.