// 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 qt6_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. 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.
\endlist

Since Qt 6.5, it is possible to change the default behavior of Qt's CMake
API by opting in to changes from newer Qt versions. If \c{REQUIRES} is
specified, all suggested changes introduced in Qt up to \c{REQUIRES} are enabled,
and using an older Qt version will result in an error.
If additionally \c{SUPPORTS_UP_TO} has been specified, any new changes introduced
in versions up to \c{SUPPORTS_UP_TO} are also enabled (but using an older Qt
version is not an error). This is similar to CMake's policy concept
(compare \l{cmake_policy}).

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 {qt6_generate_deploy_app_script}{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()}
*/