[DotGNU]Qt/Embedded and Qtopia Tutorial

[Rhys Weatherley]

Hi all,

Since some people are interested, I'll give a short tutorial on getting
Qt/Embedded and Qtopia to run on a regular GNU/Linux machine, to simulate
running applications on a PDA.  This should help people trying to
get pnet and Qt# working with PDA's who don't have access to a PDA.

You will need to fetch some files from the Trolltech FTP server.  The first
two are the actual embedded environment.  The last is needed to build the
Linux framebuffer simulator, "qvfb".  This emulates the PDA display
hardware under X11.

    ftp://ftp.trolltech.com/qtopia/snapshots/

        - get the latest qt-embedded-2.3.* snapshot from here
        - get the latest qtopia-free-1.6.* snapshot from here also

    ftp://ftp.trolltech.com/qt/source/

        - get the file qt-x11-2.3.2.tar.gz from here

Note: you must get version 2.3.2 of Qt/X11 - version 3.x will not work.

You will also need "libuuid".  If it isn't already on your system, you
can get it from the e2fsprogs distribution http://e2fsprogs.sourceforge.net/.

Unpack all of the tar.gz files that you obtained from above, and then
look at the "qtopia-free-1.6.*/README.html" file.  This contains the
official Trolltech installation instructions, which I'll now summarise.
I've tried this out locally in a clean directory on the latest snapshots,
so I know it works.

First, set the QPEDIR environment variable to point at the location
of the Qtopia source tree, and QTDIR and QTEDIR to the location of
the Qt/Embedded tree.  e.g.

    $ export QPEDIR=$HOME/qtopia-build/qtopia-free-1.6.2-snapshot-2003XXXX
    $ export QTDIR=$HOME/qtopia-build/qt-2.3.4-snapshot-2003XXXX
    $ export QTEDIR=$QTDIR

where "XXXX" is the date of your snapshot.  For the purposes of explaination,
I'm going to assume that you've unpacked everything in $HOME/qtopia-build,
but of course you can do this anywhere.

Next, build the Qt/Embedded snapshot as follows:

    $ export PATH=$QTDIR/bin:$PATH
    $ export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
    $ cd $QTDIR
    $ cp $QPEDIR/src/qt/qconfig-qpe.h src/tools/
    $ ./configure -qconfig qpe -qvfb -depths 4,8,16,32
    $ make sub-src

The next step is to build Qt/X11 2.3.2 so that you get the "qvfb" virtual
framebuffer program:

    $ export QTDIR=$HOME/qtopia-build/qt-2.3.2
    $ export PATH=$QTDIR/bin:$PATH
    $ export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
    $ cd $QTDIR
    $ ./configure
    $ make
    $ make -C tools/qvfb
    $ cp tools/qvfb/qvfb bin
    $ cp bin/uic $QTEDIR/bin

Now you are ready to build Qtopia itself, which is the palmtop environment
that is commonly used on commercial Linux PDA's like the Sharp Zaurus.

    $ cd $QPEDIR
    $ export QTDIR=$QTEDIR
    $ export PATH=$QTDIR/bin:$PATH
    $ cd src
    $ ./configure
    $ make

Phew!  Now you have all the pieces built.  To run it, you need to launch
both "qvfb" and "qpe" (Q Palmtop Environment - the original name for Qtopia).
Here is an excerpt from my "run-qpe" script:

    #!/bin/sh
    export QPEDIR=$HOME/qtopia-build/qtopia-free-1.6.2-snapshot-2003XXXX
    export QTDIR=$HOME/qtopia-build/qt-2.3.2
    export QTEDIR=$HOME/qtopia-build/qt-2.3.4-snapshot-2003XXXX
    export PATH=$QPEDIR/bin:$QTDIR/bin:$PATH
    export LD_LIBRARY_PATH=$QPEDIR/lib:$QTEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH
    export QTDIR=$QTEDIR
    qvfb &      # launch the frame buffer simulator
    sleep 3     # give qvfb time to start up
    exec qpe    # launch the Qtopia environment

To run other Qt/Embedded programs, replace "qpe" with your binary.  Or
add an icon definition to the Qtopia desktop in "$QPEDIR/apps/Applications"
and run it from the main Qtopia screen.

Technically, it is possible to build and run applications without Qtopia,
with just a raw Qt/Embedded distribution plus "qvfb".  However, getting
Qtopia working will help you diagnose problems and give you some idea
as to how the PDA's operate in practice.  The Qtopia libraries also have
a lot of handy utility classes, like "QPEApplication", that simplify
integration with the PDA environment.

If you have any questions, then just ask me.  I work part-time at Trolltech
on the Qtopia project, so I'm pretty familiar with how it all fits together.

Cheers,

Rhys.