Revision control
Copy as Markdown
// Copyright (C) 2025 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page cross-compiling-qt.html
\title Cross-compiling Qt
\brief Building Qt for a platform different from your host platform.
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 \l{Creating the
host build of Qt}.
\section1 Terms and definitions
\e Cross-compiling means configuring and building for a target platform
that's different from your host platform.
The \e host is the computer you are building Qt on, for example a Linux
machine. The \e 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 \e host and are therefore called the
\e{host tools}. These host tools are part of a \e{host build} of Qt. This
host build must be prepared as a prerequisite to building Qt for the
\e{target platform}.
A \e{minimal host build} of Qt is a \e{host build} of Qt that only contains
the \e{host tools} necessary to create a \e{target build} of Qt.
Qt is built with CMake, and CMake needs a \e{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 \e sysroot. That is a
self-contained environment that includes all necessary files and libraries
required for compiling and linking applications.
\section1 General notes on the host build of Qt
During the build of Qt for the target, tools such as \c moc, \c rcc, \c
qmlcachegen, \c 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 \c configure or \c 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 \e 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.
\section1 Creating the host build of Qt
See \l{Building Qt Sources}{the documentation of the desired host} for
details on how to build Qt for that platform.
To build a \e{minimal host Qt}, use the following build command after
configuring Qt:
\badcode
mkdir ~/QtHostBuild
cd ~/QtHostBuild
~/QtSource/configure -developer-build -nomake tests
cmake --build . --target host_tools
\endcode
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.
\section1 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
\badcode
~/QtSource/configure -qt-host-path ~/QtHostBuild ...target-specific options...
\endcode
When using CMake directly, you use
\badcode
cmake -S ~/QtSource -DQT_HOST_PATH=~/QtHostBuild ...target-specific options...
\endcode
See \l{Building Qt Sources}{the documentation of the desired target} for
target-specific options.
*/