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

# Getting Started

- Introduction
- Acceptable directory characters
- Source or rpm?
- Download Procedure
- Qtopia Dependencies / Prerequisites
  - Video4Linux
  - zlib
  - libuuid (aka luuid)
  - libjpeg
  - xorg or x11
- Install Procedures (for newbies)
  - Installing rpm Packages
  - Installing Source (.tar.*) Packages
- Unpacking and Installing Qtopia

## Introduction

Qtopia is available in several different packages. Each package has a different license and is targeted at a different type of customer. Some packages contain the full source code, others only contain binaries, and some contain a mixture of binaries and source code. The documentation is the same for all packages.

The documentation is intended to be the one stop shopping point for the majority of your questions. You can find the documentation in the `doc/html` directory of your Qtopia package. You can also visit http://doc.trolltech.com and go to the Qtopia 2.1 section to browse through the latest version of the documentation.

For information about compiling and running the SDK example application, please refer to the Compile and Run SDK Example Application document. See also Running Qtopia.

## Acceptable directory characters

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

## Source or rpm?

You can download and install either a Qtopia rpm or a Qtopia source package.

Using an rpm will save you compile time and allow you to start developing your own Qtopia applications sooner. To download an rpm, go to the Qtopia Download Page and select the rpm for your platform, but please be advised that commercial packages are not available here. Please contact a Trolltech sales representative via sales@trolltech.com if you require a commercial package.

RPM packages are built for a specific Linux distribution. At the time of writing we produce rpm packages for Red Hat 9, SuSE 8.2 and SuSE 8.0. The differences between the rpm packages relate to file locations and such: from a functional point of view the packages are exactly the same. When you download a package you should select a package that matches your distribution.

The rpm packages generally do not contain any source code, however if some has been included for demonstartion purposes it will not be the full source code. For instance `qtopia-phone-demo-2.1.1-suse82.i386.rpm` is a binary only package. You can download and install it and it will run a demo version of Qtopia Phone on your desktop machine. You cannot use this package to create your own Qtopia based application or to deploy Qtopia Phone on a device.

If you have any questions regarding which package will best meet your needs please contact sales@trolltech.com and they will assist you in making a choice.

A Qtopia source package is, as the name implies, a package of source code. It contains all the source code and scripts that you need in order to build your own Qtopia binaries. Having access to all the source code is also great for debugging and (depending on your license) for enhancing the code.

## Download Procedure

There are several ways to download Qtopia packages. You can download free packages from the public Trolltech server or if you have a valid license you will have access to your own personalized site on our distribution server or you may have been given access to our temporary ftp server.

HINT: If you know all about downloading files and using `md5sum` then you can safely skip the rest of this section. To proceed to the next section click here.

On the download site you will see a list of files that have been made available. Just select the files you need and download them to an empty directory on your system. Usually 'selecting' means right-clicking on a file and clicking the "Save As..." option.

In the list there will be a file named `md5sum.txt`. This file contains checksums for all the available files and it is strongly recommended that you download this file along with the others. When you have downloaded all files, including `md5sum.txt` simply run:

        md5sum -c md5sum.txt

This will generate checksums for all the files that you have downloaded and compare them with the checksum that is given in the `md5sum.txt` file. If the checksums are the same you'll get something like:

        README.html: OK
        build_qtopiaphone: OK
        qt-embedded-2.3.10-commercial.tar.gz: OK
        qt-x11-2.3.2-commercial.tar.gz: OK
        qt-x11-commercial-3.3.0.tar.gz: OK
        tmake-1.13.tar.gz: OK

If on the other hand a file was corrupted during downloading the report will look something like this:

        README.html: FAILED
        build_qtopiaphone: OK
        md5sum: WARNING: 1 of 2 computed checksums did NOT match

If this happens, please remove the bad file from your system and try downloading it again. If problems persist, please contact Trolltech.

If you haven't downloaded all files from the ftp site then the `md5sum.txt` file will contain more checksums than are generated on your system. In this case you'll get something like:

        md5sum: README.html: No such file or directory
        README.html: FAILED open or read
        qtopia-phone-source-2.1.1.tar.gz: OK
        md5sum: WARNING: 1 of 2 listed files could not be read

If you didn't download the README.html file (and didn't intend to) then just ignore the message or else download the missing file(s) and try again.

Now that you have downloaded all files and put them in an empty directory on your system it's time to unpack the packages.

## Qtopia Dependencies / Prerequisites

In order for Qtopia to run as intended the following prerequisites must be satisfied:

- Linux kernel that provides shared memory, mmap, and sockets.
- Linux with framebuffer support.
- Linux with OSS sound support, or ALSA sound support with OSS compatability. Refer to The Qtopia A/V & Appearance FAQ for further details.

The following libraries are also required:

- Video4Linux
- zlib
- libuuid (aka luuid)
- libjpeg
- xorg or x11

Note also that freetype http://freetype.sourceforge.net/index2.html is recommended though not required.

### Video4Linux

The Camera application requires a kernel with Video4Linux version 1 support. This is not provided with Qtopia.

Please refer to the official Video for Linux resources site for details about this API.

### zlib

The zlib library can be downloaded from the http://www.gzip.org/zlib/ site.

### libuuid (aka luuid)

The uuid library is not provided with Qtopia. It can be downloaded from the http://e2fsprogs.sourceforge.net/ site.

Alternately if you have a Suse linux distribution it is likely to be provided by the package `e2fsprogs-devel`. On Debian it is provided by `uuid-dev`. The library should be in the standard location, eg /usr/lib/libuuid.so.

To check that the package is installed use your package management tool, for example

     rpm -qa | grep e2fsprogs

. If it is not there then install it (and any dependencies) from your distributor's CD's or local mirror. For example, if you have suse 9.1 then go use http://ds.thn.htu.se/linux/suse/9.1/suse/i586/e2fsprogs-devel-1.34-115.i586.rpm to download the `e2fsprogs`.

Note that not having this will produce the following linker error:

    /usr/lib/gcc-lib/i586-suse-linux/3.3.3/../../../../i586-suse-linux/bin/ld:
    cannot find -luuid

If the library is installed and you still experienced this linker error then check your -L and -R settings to Qtopia's `./configure` script and make sure the actual location of the library is set in the script.

Information about cross compiling libuuid can be found in the System Integrator's Guide.

### libjpeg

The jpeg library is not provided with Qtopia. Qtopia requires that Qt/Embedded is configured with JPEG support.

The libjpeg library can be downloaded from the http://www.ijg.org/ site.

Alternately if you have a Suse linux distribution it is likely to be provided by the package `libjpeg`. The library should be in the standard location, eg /usr/lib/libjpeg.so.

To check that the package is installed use your package management tool, for example

     rpm -qa | grep libjpeg

. If it is not there then install it (and any dependencies) from your distributor's CD's or local mirror.

Information about cross compiling libjpeg can be found in the System Integrator's Guide.

### xorg or x11

These development packages are available from the following sites:

- http://www.xfree86.org/
- http://xorg.freedesktop.org

## Install Procedures (for newbies)

We again have to differentiate between rpm packages and source `(.tar.gz)` packages. Whatever the package type, once you have installed the package there will be a LICENSE file and a README file in the root package directory. The LICENSE file will describe all your rights and obligations and the README file will address any last minute issues that may have arisen. Please take the time to read both files.

To read only a specific installation section select from the following: rpm package installation or tar.gz package installation .

### Installing rpm Packages

An rpm package is easy to install. You can either use the GUI tools that are provided by your specific distribution or use command line tools. The GUI tools are different for each distribution so we won't even try to describe them in detail. Generally speaking it would be something like opening your file browser and clicking on an rpm file. The file browser should recognize the rpm file, open a dialog and ask you if you want to install the rpm. To actually install the rpm you need to enter the root (administrator) password somewhere and the system will handle the rest for you. Any error situations will be reported to you, but if all goes well you'll be ready to proceed once this is done.

Qtopia rpm packages are usually installed in `/opt/Qtopia`. There will be a bin directory that contains all the binaries and several other directories that contain libraries, configuration files and so on.

If your rpm is a Software Development Kit (SDK) package it may also contain an `arm` subdirectory. In this subdir you will find a copy of everything in `/opt/Qtopia` with the exception that all the binaries will have been built for an ARM device.

HINT: If you know all about using `rpm` you can skip the rest of this section. To proceed to the next section (Installing Qtopia) click here.

To install an rpm package from the command line you do the following:

- First you need to log in as root:

          su and enter the root password upon request to log in as root

- Make sure that there isn't already an installed Qtopia rpm package on your system. For example, you cannot install both a Qtopia Developer SDK and a Qtopia Commercial SDK rpm package. The only exception to this rule is Qtopia Desktop which can be combined with any other Qtopia rpm package, but you cannot install Qtopia Desktop if an older version of Qtopia Desktop is already installed. To check which Qtopia packages are installed on your system do the following:

          rpm -qa | grep qtopia to get a list of all currently installed Qtopia rpms on your system

- If another Qtopia package is installed, or if an older version of your package is installed then uninstall it before proceeding. To uninstall a package use:

          rpm -e packagename

  The "packagename" is the name of the package as the rpm 'knows' it and it is slightly different from the file name. If you use the `rpm -qa` command as described before you will get the exact name of the package that you need in order to uninstall the package.

- The rpm tool also provides an option to upgrade an existing package. Technically this means that if an older version of the package already exists on your system you don't have to uninstall it, instead you can choose to update the files that have changed.

  To avoid potential problems however, we recommend that you ALWAYS uninstall the old package before installing the new package.

- Now that we have removed all old packages it is time to install the new package:

          rpm -ivh package-file-name

- Log out as root:

          exit

If all went well your package has now been installed and is ready to run!

For information about running Qtopia please go to Running Qtopia

For more help with the rpm command please type `man rpm` on the command line and you get all the information you need.

### Installing Source (.tar.*) Packages

Source packages come in two varieties: `.tar.gz` and `.tar.bz2` files. The contents of the packages is exactly the same and the different file extensions are simply the result of the two different compression algoritms used to make the packages. Some people prefer `gz` (faster), some prefer `bz2` (smaller). Choose one of the two, but don't download both packages as that will just cost you bandwith without adding any benefit.

HINT: If you know all about using `tar` this section is probably a bit boring. To proceed to the next section (Installing Qtopia) click here.

To unpack a `.tar.gz` package you have to do the following:

        cd into the directory where you want to install the package
        tar -xzf package-file-name

To unpack a `.tar.bz2` package you have to do the following:

        cd into the directory where you want to install the package
        tar -xjf package-file-name

For more help with the tar command please type `man tar` on the command line and you will get all the information you need. In both cases (`.tar.gz` and `.tar.bz2`) the tar package will be unpacked in a new subdirectory. The name of the subdirectory is defined in the package and is usually a close match to the package name. For example, the package `qtopia-phone-source-2.1.1.tar.gz` will be unpacked into a subdir named `qtopia-phone-2.1.1` and `qtopia-refboard-2.1.1.tar.gz` will be unpacked into a subdir named `qtopia-refboard-2.1.1`.

## Unpacking and Installing Qtopia

If you only have a Qtopia rpm package then you just have to follow the guidelines provided in the "Installing rpm packages" section and you're done.

If you are adding support for a new device then first read system-integrators-guide.html.

It is also possible that the ftp site provides you with both rpm packages and source packages. In this case the rpm package is most likely a demo version of Qtopia which you have to install using the guidelines provided in the "Installing rpm packages" section. You also have to install the source packages using the following guidelines.

To install and build Qtopia from the source code you actually need several packages. These packages are:

- Qtopia 2.x
- Qt/Embedded 2.3.10 (or higher, but always a 2.3 version)
- libuuid (aka luuid) \i JPEG library and header files. These can be obtained from \link http://www.ijg.org the Independent JPEG Group site.

The remaining packages are available to commercial licence holders as a Qtopia Tools package. They can also be individually installed and built. If you are using the Qtopia Tools package then you can skip to the section Install Qt/Embedded . These remaining packages are required:

- Qt 2.3.2 for X11 (for emulated desktop development)
- Qt 3.3.0 (or higher) for X11 (required for the language tools and the phone simulator)
- tmake 1.13 (or higher)

The Qtopia source package comes in several flavours. At the time of writing there is a PDA version, a Phone version and a Core version. The install procedure for all three is exactly the same, it is only the filenames which are slightly different. In this example we assume you are installing Qtopia Phone. For Qtopia PDA please replace "phone" with "pda" where appropriate.

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 for your geographic location. 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.

To install the packages do the following:

- Install TMake
  TMake is used for building Qt/Embedded. Qtopia is built using QMake, which is included in the Qtopia source package.

          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 like 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 3.3
  Qt 3.3 is used to build more tools like the phone simulator and translation tools. The first is only relevant for a Qtopia Phone package, the second is important for all Qtopia products. You can use it to internationalize your product to any language you wish. We assume that you have the commercial version of Qt 3.3-X11. Please adjust the filenames if you have a different package.

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

- Install Qt/Embedded
  We assume you have the commercial Qt/Embedded package. If you use the free package you should adjust the filenames accordingly. We also assume you have Qt/Embedded 2.3.10 (which was the Qt/Embedded version released with Qtopia 2.1.1). If you have a newer version of Qt/Embedded then please replace the version number below as appropriate. Please be advised that Qtopia 2.1 does NOT compile with version 3.0 or above of Qt/Embedded. If you are using the Qtopia Tools package then

          export TMAKEDIR=/opt/QtopiaTools/tmake
          export QT2DIR=/opt/QtopiaTools/qt2
          export DQTDIR=/opt/QtopiaTools/qt3

  All users will need to

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

- Install Qtopia
  We assume that you have the Qtopia Phone source package. Please adjust the filenames if you have a different Qtopia package. For example, `qtopia-pda-source-2.1.1.tar.gz` etc.

          cd ~/dev
          tar -xzf qtopia-phone-source-2.1.1.tar.gz
          export QPEDIR=$PWD/qtopia-phone-2.1.1

You should now have installed all required packages. Each package is in it's own subdirectory, but you will be spending most of the time dealing with the `Qtopia` subdirectory. 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 Qtopia, 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
- 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

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

You are now ready to build Qtopia. For instructions please refer to Building Qtopia from Source .