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:
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
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
-platform option to change the specification for the host platform (where compilation will take place).
-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
-xplatform option to make Qt for Embedded Linux aware of the custom
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
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.
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
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
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
-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.
© 2016 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.