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.