qt_standard_project_setup.qdoc

Go to the documentation of this file.

// Copyright (C) 2021 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qt-standard-project-setup.html
\ingroup cmake-commands-qtcore
 
\title qt_standard_project_setup
\keyword qt_standard_project_setup()
 
\summary {Setup project-wide defaults to a standard arrangement.}
 
\include cmake-find-package-core.qdocinc
 
\cmakecommandsince 6.3
 
\section1 Synopsis
 
\badcode
qt_standard_project_setup(
    [REQUIRES <version>]
    [SUPPORTS_UP_TO <version>]
    [I18N_TRANSLATED_LANGUAGES <language...>]
    [I18N_SOURCE_LANGUAGE <language>]
)
\endcode
 
\versionlessCMakeCommandsNote qt6_standard_project_setup()
 
\section1 Description
 
This command simplifies the task of setting up a typical Qt application.
It would usually be called immediately after the first \c{find_package(Qt6)}
call, normally in the top level \c{CMakeLists.txt} file and before any targets
have been defined. If you call it later, it does not apply to any targets
defined before, with possibly confusing results. It does the following things:
 
\list
\li The standard CMake variables \c{CMAKE_AUTOMOC} and \c{CMAKE_AUTOUIC}
    are set to true if they are not already defined.
    This enables all Qt-related autogen features by default for subsequently
    created targets in the current directory scope and below.
\li CMake's \l{GNUInstallDirs} module is automatically included. This defines
    appropriate defaults for variables like \c{CMAKE_INSTALL_BINDIR},
    \c{CMAKE_INSTALL_LIBDIR}, and so on.
\li When targeting Windows, if the \c{CMAKE_RUNTIME_OUTPUT_DIRECTORY} variable
    is not already set, it will be set to
    \c{${CMAKE_CURRENT_BINARY_DIR}}.
\li When target platforms other than Apple or Windows, \c{CMAKE_INSTALL_RPATH}
    will be augmented as described below.
\li CMake's \l USE_FOLDERS property is set to \c{ON}, and \l QT_TARGETS_FOLDER is
    set to \c{QtInternalTargets}. IDEs that support folders will display
    Qt-internal targets in this folder.
\li When using the Xcode generator with CMake 4.4 or later,
    \c{CMAKE_XCODE_LINK_BUILD_PHASE_MODE} is set to \c{KNOWN_LOCATION} if it is
    not already defined. This causes linked libraries and frameworks to be added
    to Xcode's \e{Link Binary With Libraries} build phase, making them visible
    in the Xcode target's \e{General} tab rather than being passed as raw linker
    flags.
\endlist
 
Since Qt 6.5, it is possible to change the default behavior of Qt's CMake
API by opting in to behavior changes from newer Qt versions via
\l{Qt CMake policies}. This is similar to CMake's own policy concept
(compare \l{cmake_policy}). If \c{REQUIRES} is specified, all policies
introduced in Qt versions up to and including \c{REQUIRES} are automatically
set to \c{NEW}, and using an older Qt version will result in an error.
For example, specifying \c{REQUIRES 6.8} enables policies QTP0001 through
QTP0005. If \c{SUPPORTS_UP_TO} is also specified, policies up to that version
are enabled as well, but without requiring that particular Qt version to be
present.
 
The following policies are available:
 
\annotatedlist qt-cmake-policies
 
See \l qt_policy() for details on manually setting individual policies.
 
On platforms that support \c{RPATH} (other than Apple platforms), two values
are appended to the \c{CMAKE_INSTALL_RPATH} variable by this command.
\c{$ORIGIN} is appended so that libraries will find other libraries they depend
on in the same directory as themselves. \c{$ORIGIN/<reldir>} is also appended,
where \c{<reldir>} is the relative path from \c{CMAKE_INSTALL_BINDIR} to
\c{CMAKE_INSTALL_LIBDIR}. This allows executables installed to
\c{CMAKE_INSTALL_BINDIR} to find any libraries they may depend on installed to
\c{CMAKE_INSTALL_LIBDIR}. Any duplicates in \c{CMAKE_INSTALL_RPATH} are
removed. In practice, these two values ensure that executables and libraries
will find their link-time dependencies, assuming projects install them to the
default locations the \l{install(TARGETS)} command uses when no destination is
explicitly provided.
 
To disable folder support for IDEs, set \l USE_FOLDERS to \c OFF before or after
the call to \c{qt_standard_project_setup}.
 
The \c{qt_standard_project_setup()} command can effectively be disabled by
setting the \l{QT_NO_STANDARD_PROJECT_SETUP} variable to true.
 
\sa qt_generate_deploy_app_script()
\sa qt_policy()
 
\section1 Internationalization
 
Since Qt 6.7, it is possible to specify the languages that are used for project
internationalization with the \c I18N_TRANSLATED_LANGUAGES argument. See \l
QT_I18N_TRANSLATED_LANGUAGES for details.
 
Use I18N_SOURCE_LANGUAGE to specify the language that translatable strings are
written in. By default, \c en is used. See \l QT_I18N_SOURCE_LANGUAGE for
details.
 
\section1 Example
 
\include cmake-generate-deploy-app-script.qdocinc
 
\sa {Automatic Determination of .ts File Paths}{qt_add_translations()}
*/