Cross-compiling Qt

This page describes the general process and requirements of cross-compiling Qt.

If you're just looking for a way to build a host Qt, see Creating the host build of Qt.

Terms and definitions

Cross-compiling means configuring and building for a target platform that's different from your host platform.

The host is the computer you are building Qt on, for example a Linux machine. The target is the device you're building Qt for, for example an Android tablet.

When building Qt, several tools are run that generate code or do some other processing. These tools run on the host and are therefore called the host tools. These host tools are part of a host build of Qt. This host build must be prepared as a prerequisite to building Qt for the target platform.

A minimal host build of Qt is a host build of Qt that only contains the host tools necessary to create a target build of Qt.

Qt is built with CMake, and CMake needs a toolchain file when cross-compiling. This file contains information about the target platform and the used toolchain. See the CMake documentation on cross-compiling.

For some target platforms, the Qt configure script automatically selects the file. See the documentation that's specific for the desired target platform for details.

For some target platforms, you need to specify a sysroot. That is a self-contained environment that includes all necessary files and libraries required for compiling and linking applications.

General notes on the host build of Qt

During the build of Qt for the target, tools such as moc, rcc, qmlcachegen, qsb, and others, are invoked from there. For example, if one cross-compiles for ARM on an x64 machine, a local x64 build of the same Qt version must be made available first. The path to this Qt build will be passed to configure or cmake. The host build of Qt is usually a regular build of Qt for your host device.

The host build of Qt must contain all necessary host tools for building Qt for the target platform. For example, if your target Qt is supposed to support Qt Quick, the host Qt must contain qsb, the shader compiler. An easy way to ensure that the host Qt provides all necessary tools is to build the same Qt modules on the host that you'll need on the target.

Avoid building the host Qt statically if the target Qt is built shared. A static build of Qt might not contain all tools necessary to build a shared Qt.

Ensure you use the same version of Qt for the host and target Qt to avoid incompatibility issues.

Creating the host build of Qt

See the documentation of the desired host for details on how to build Qt for that platform.

To build a minimal host Qt, use the following build command after configuring Qt:

 mkdir ~/QtHostBuild
 cd ~/QtHostBuild
 ~/QtSource/configure -developer-build -nomake tests
 cmake --build . --target host_tools

This build won't be suitable for developing Qt programs for your host platform, but it will contain the tools necessary to cross-build Qt.

Specifying the host build of Qt when cross-compiling

When cross-compiling, you must point the target Qt to the location of the host Qt.

When using the configure script, you use

 ~/QtSource/configure -qt-host-path ~/QtHostBuild ...target-specific options...

When using CMake directly, you use

 cmake -S ~/QtSource -DQT_HOST_PATH=~/QtHostBuild ...target-specific options...

See the documentation of the desired target for target-specific options.