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 cmake-making-qt-available.html
\title Making Qt available in CMake projects
\brief Provides an overview of how to make Qt's packages available in CMake projects.
Currently the only supported method of making Qt available for user projects is by
having it pre-installed on the system, or any equivalent workflow that builds
Qt ahead of time and makes it available to
\c{vcpkg}.
When using \l{\QC Documentation}{\QC} or \c{qt-cmake} (\c{qt-cmake.bat} on Windows),
the Qt installation location is automatically forwarded to the underlying CMake call.
When using \c{cmake} directly, the general search paths used by CMake should cover most non-user
installations of Qt. For more control over which Qt package to use, you can pass
\c{Qt6_ROOT} as an environment or cache variable pointing to the Qt installation path, or by
adding or appending to the \c{CMAKE_PREFIX_PATH} in a similar way. For
example, if the installation path is \tt{"~/Qt/\QtVersion/gcc_64"}, you would pass it on the
command line as \tt{-DQt6_ROOT=$HOME/Qt/\QtVersion/gcc_64}.
\note When cross-compiling (compiling for a platform other than the one you
are on, such as WebAssembly or Android) and when using vanilla \c{cmake},
set \c{CMAKE_TOOLCHAIN_FILE} instead of search paths like \c{Qt6_ROOT} or \c{CMAKE_PREFIX_PATH}.
On Linux, the toolchain file (specific to a particular target platform) is typically
located at a path similar to this:
\tt{"~/Qt/\QtVersion/wasm_singlethread/lib/cmake/Qt6/qt.toolchain.cmake"}. It sets
the required variables like \c{CMAKE_PREFIX_PATH}, \c{CMAKE_FIND_ROOT_PATH},
and \c{QT_HOST_PATH}.
\quotefromfile snippets/cmake/import_qt_minimal.cmake
\skipto cmake_minimum_required
\printuntil
The Qt package is split into various modules that you need to include
depending on the scope of your project, most basic of which is
\quotefromfile snippets/cmake/helloworld_qtcore.cmake
\skipto find_package
\printuntil find_package
Modern CMake supports other dependency providers such as \c{FetchContent},
however using Qt with \c{FetchContent} is not supported due to a tight integration
of Qt features inside CMake itself. Adding Qt sources via \c{add_subdirectory} and Git
submodules is not supported either.
\note Calling \c{find_package(Qt6)} in a subdirectory other than where it is used, or
inside a \c{function} is not supported. Doing so can cause various failures in
unpredictable locations.
Instead, repeatedly call \c{find_package(Qt6)} in all subdirectory scopes that use
Qt functions, or move the \c{find_package(Qt6)} call to the root \c{CMakeLists.txt}.
*/