Qt Reference Documentation

# Cross-Compiling Qt for Embedded Linux Applications

Cross-compiling is the process of compiling an application on one machine, producing executable code for a different machine or device. To cross-compile a Qt for Embedded Linux application, use the following approach:

Note: The cross-compiling procedure has the configuration process in common with the installation procedure; i.e., you might not necessarily have to perform all the mentioned actions depending on your current configuration.

## Step 1: Set the Cross-Compiler's Path

Specify which cross-compiler to use by setting the `PATH` environment variable. For example, if the current shell is bash, ksh, zsh or sh:

     export PATH=path/to/cross/compiler:$PATH

## Step 2: Create a Target Specific qmake Specification

The qmake tool requires a platform and compiler specific `qmake.conf` file describing the various default values, to generate the appropriate Makefiles. The standard Qt for Embedded Linux distribution provides such files for several combinations of platforms and compilers. These files are located in the distribution's `mkspecs/qws` subdirectory.

Each platform has a default specification. Qt for Embedded Linux will use the default specification for the current platform unless told otherwise. To override this behavior, you can use the `configure` script's `-platform` option to change the specification for the host platform (where compilation will take place).

The `configure` script's `-xplatform` option is used to provide a specification for the target architecture (where the library will be deployed).

For example, to cross-compile an application to run on a device with an ARM architecture, using the GCC toolchain, run the configure script at the command line in the following way:

     ./configure -embedded arm -xplatform qws/linux-arm-g++ <other options>

If neither of the provided specifications fits your target device, you can create your own. To create a custom `qmake.conf` file, just copy and customize an already existing file. For example:

     cp path/to/QtEmbedded/mkspecs/qws/linux-mips-g++/...
        path/to/QtEmbedded/mkspecs/qws/linux-myarchitecture-g++/...

Note: When defining a mkspec for a Linux target, the directory must be prefixed with "linux-". We recommend that you copy the entire directory.

Note also that when providing you own qmake specifcation, you must use the `configure` script's `-xplatform` option to make Qt for Embedded Linux aware of the custom `qmake.conf` file.

## Step 3: Provide Architecture Specific Files

Starting with Qt 4, all of Qt's implicitly shared classes can safely be copied across threads like any other value classes, i.e., they are fully reentrant. This is accomplished by implementing reference counting operations using atomic hardware instructions on all the different platforms supported by Qt.

To support a new architecture, it is important to ensure that these platform-specific atomic operations are implemented in a corresponding header file (`qatomic_ARCH.h`), and that this file is located in Qt's `src/corelib/arch` directory. For example, the Intel 80386 implementation is located in `src/corelib/arch/qatomic_i386.h`.

See the Implementing Atomic Operations documentation for details.

## Step 4: Provide Hardware Drivers

Without the proper mouse and keyboard drivers, you will not be able to give any input to your application when it is installed on the target device. You must also ensure that the appropriate screen driver is present to make the server process able to put the application's widgets on screen.

Qt for Embedded Linux provides several ready-made mouse, keyboard and screen drivers, see the pointer handling, character input and display management documentation for details.

In addition, custom drivers can be added by deriving from the QWSMouseHandler, QWSKeyboardHandler and QScreen classes respectively, and by creating corresponding plugins to make use of Qt's plugin mechanism (dynamically loading the drivers into the server application at runtime). Note that the plugins must be located in a location where Qt will look for plugins, e.g., the standard `plugin` directory.

See the How to Create Qt Plugins documentation and the Plug & Paint example for details.

## Step 5: Build the Target Specific Executable

Before building the executable, you must specify the target architecture as well as the target specific hardware drivers by running the `configure` script:

     cd path/to/QtEmbedded
     ./configure -embedded <architecture> -qt-kbd-<keyboarddriver>
                 -qt-mouse-<mousedriver> -qt-gfx-<screendriver>

It is also important to make sure that all the third party libraries that the application and the Qt libraries require, are present in the tool chain. In particular, if the zlib and jpeg libraries are not available, they must be included by running the `configure` script with the `-L` and `-I` options. For example:

     cd path/to/QtEmbedded
     ./configure  <other options>
                  -L /path/to/libjpeg/libraries -I /path/to/libjpeg/headers

The JPEG source can be downloaded from http://www.ijg.org/. The Qt for Embedded Linux distribution includes a version of the zlib source that can be compiled into the Qt for Embedded Linux library. If integrators wish to use a later version of the zlib library, it can be downloaded from the http://www.gzip.org/zlib/ website.

Then build the executable:

     cd path/to/myApplication
     qmake -project
     qmake
     make

That's all. Your target specific executable is ready for deployment.

See also: Qt for Embedded Linux Architecture and Deploying Qt for Embedded Linux Applications.