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 \version (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-\version-commercial.tar.gz export QTEDIR=$PWD/qt-\version 

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 \version 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.2.0 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.