cmake-variables.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
 
/*!
\group cmake-variables-qtqml
\title CMake Global Variables in Qt6 Qml
 
\l{CMake Command Reference#Qt6::Qml}{CMake Commands} know about the following
global CMake variables:
 
*/
 
/*!
\page cmake-variable-qt-qml-output-directory.html
\ingroup cmake-variables-qtqml
 
\title QT_QML_OUTPUT_DIRECTORY
 
\summary{Base output directory below which QML modules will be created by default.}
 
The \l qt_add_qml_module() command accepts an
\c OUTPUT_DIRECTORY argument which specifies where the QML module's \c qmldir
file, typeinfo file and plugin library will be created. When that argument is
not used, the default value is based on the \c QT_QML_OUTPUT_DIRECTORY variable,
if it is set. If \c QT_QML_OUTPUT_DIRECTORY is not set, the default value
depends on the type of backing target (see the
\l{qt_add_qml_module#OUTPUT_DIRECTORY}{OUTPUT_DIRECTORY} documentation for
details).
 
When \c QT_QML_OUTPUT_DIRECTORY is set, the default output directory will be
formed by appending the QML module's \e{target path} (which is based on the
module URI) to \c QT_QML_OUTPUT_DIRECTORY.
The \c QT_QML_OUTPUT_DIRECTORY will also be added to the import path of the
\c qmllint and \c qmlcachegen tooling targets, allowing them to find other QML
modules under the same base location. This allows the project to use a source
directory structure that doesn't exactly match the URI structure of the QML
modules, or to merge sets of QML modules under a common base point.
 
\sa {Setting CMake variables and properties}
*/
 
/*!
\page cmake-variable-qt-qml-generate-qmlls-ini-no-cmake-calls.html
\ingroup cmake-variables-qtqml
 
\title QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS
 
\summary{Customizes the value of no-cmake-calls in .qmlls.ini files for \QMLLS.}
\cmakevariablesince 6.10
 
\c QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS is a boolean that controls the \c no-cmake-calls value in
\c{.qmlls.ini} files generated with the \l{QT_QML_GENERATE_QMLLS_INI} option. Set it to \c ON to disable
CMake calls by \QMLLS.
 
As this variable is used for IDE integration, it should normally not be set in a project itself, but
passed to CMake via an IDE or manually by passing
\badcode
-DQT_QML_GENERATE_QMLLS_INI=ON -DQT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS=ON
\endcode
to the cmake executable.
 
This variable has no effect if \l{QT_QML_GENERATE_QMLLS_INI} is disabled.
 
\sa QT_QML_GENERATE_QMLLS_INI, {Configuring Automatic CMake Builds}
\sa {Setting CMake variables and properties}
*/
 
/*!
\page cmake-variable-qt-qml-generate-qmlls-ini.html
\ingroup cmake-variables-qtqml
 
\title QT_QML_GENERATE_QMLLS_INI
 
\summary{Enables autogeneration of .qmlls.ini files for \QMLLS.}
\warning This variable is deprecated since Qt 6.10. No replacement needed.
\cmakevariablesince 6.7
 
\c QT_QML_GENERATE_QMLLS_INI is a boolean that describes whether
\l qt_add_qml_module() calls generate \c{.qmlls.ini} files inside
the \b{source folder}, into each subdirectory with a CMakeLists.txt file creating a QML module.
If \c{.qmlls.ini} files already exist there, then they are overwritten.
 
\note Using \c QT_QML_GENERATE_QMLLS_INI requires a CMake version >= 3.19.
 
These \c{.qmlls.ini} files contain the path to the last configured build directory,
and is needed by \l{\QMLLS} to find user defined modules. See also
\l{\QMLLS} about the other ways of passing build folders to \QMLLS.
 
 
As this variable is used for IDE integration, it should normally not be set in a project itself, but
passed to CMake via an IDE or manually by passing
\badcode
-DQT_QML_GENERATE_QMLLS_INI=ON
\endcode
to the cmake executable.
 
\warning The files generated by \c QT_QML_GENERATE_QMLLS_INI are only valid for the current
configuration and should be ignored by your version control system. For Git, add \tt{**\/.qmlls.ini}
to your top-level project \c{.gitignore}, for example.
The globbing is required because .qmlls.ini files are generated in \e{all source
subdirectories} that define QML Modules.
 
\sa QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS, {Configuring Automatic CMake Builds}
\sa {Setting CMake variables and properties}
*/
 
/*!
\page cmake-variable-qt-qml-no-cachegen.html
\ingroup cmake-variables-qtqml
 
\title QT_QML_NO_CACHEGEN
 
\summary{Disables compilation of QML files into bytecode or C++ code.}
\cmakevariablesince 6.8.1
 
\c QT_QML_NO_CACHEGEN is a CMake variable that can be set to disable the compilation of QML files
into bytecode or C++ code for QML targets created by
\l qt_add_qml_module().
 
It has the same effect as setting the \c{NO_CACHEGEN} option of
\l qt_add_qml_module(), but allows doing so on a per-directory or project
basis.
 
Turn on this option to reduce the number of build steps necessary to complete a build, and
thereby shorten the develop-debug iteration cycle.
 
To minimize application size, turn off this option, and instead use
\l{QT_DISCARD_FILE_CONTENTS}{QT_DISCARD_FILE_CONTENTS} to remove the QML files embedded into the
resource system.
 
The variable can be set in the project's CMakeLists.txt as follows:
\badcode
set(QT_QML_NO_CACHEGEN TRUE)
qt_add_qml_module(MyModule
    URI MyModule
    VERSION 1.0
    ...
)
\endcode
 
\sa {Setting CMake variables and properties}
*/
 
/*!
\page cmake-variable-qt-qml-generate-aotstats.html
\ingroup cmake-variables-qtqml
 
\title QT_QML_GENERATE_AOTSTATS
 
\summary{Controls whether QML Compiler statistics collection is enabled.}
\cmakevariablesince 6.8.3
 
When a QML project is configured using \l qt_add_qml_module(), by default,
\l{QML script compiler#Obtaining statistics about the compilation of functions and bindings}{statistics}
from the compilation of QML code will be collected. You can explicitly opt in
or out of this by setting the \c{QT_QML_GENERATE_AOTSTATS} variable. It can be
set project-wide by passing
\badcode
-DQT_QML_GENERATE_AOTSTATS=OFF
\endcode
to the CMake executable, or by setting it directly in the corresponding
CMakeLists.txt file before the first call to \l qt_add_qml_module().
\badcode
set(QT_QML_GENERATE_AOTSTATS OFF)
\endcode
 
\sa {Setting CMake variables and properties}
*/
 
/*!
\page cmake-variable-qt-qmllint-no-context-property-dump.html
\ingroup cmake-variables-qtqml
 
\title QT_QMLLINT_CONTEXT_PROPERTY_DUMP
 
\summary{Enables dumping of context properties in lint targets.}
\cmakevariablesince 6.11
 
When the \c QT_QMLLINT_CONTEXT_PROPERTY_DUMP variable is enabled, \l{qmllint-auto}{linting targets}
created by \l qt_add_qml_module() will run \l qmlcontextpropertydump before running \l qmllint. This
allows \l qmllint to warn on the usage of context properties in QML.
 
To enable this feature, set the \c QT_QMLLINT_CONTEXT_PROPERTY_DUMP variable using
one of the following methods:
 
\list
    \li Pass the option to the CMake executable:
        \badcode
        -DQT_QMLLINT_CONTEXT_PROPERTY_DUMP=ON
        \endcode
 
    \li Add the setting to your \c CMakeLists.txt file before the first call to
        \l qt_add_qml_module():
        \badcode
        set(QT_QMLLINT_CONTEXT_PROPERTY_DUMP ON)
        \endcode
\endlist
 
\sa {Setting CMake variables and properties}
*/
 
/*!
\page cmake-variable-qt-qml-no-qml-preview.html
\ingroup cmake-variables-qtqml
 
\title QT_QML_NO_QML_PREVIEW (global property)
 
\summary{Controls whether qmlpreview support is automatically set up for executables linking against Qt6::Qml.}
\cmakevariablesince 6.12
 
By default, every executable target that links against \c{Qt6::Qml}
automatically gets \l qmlpreview support set up for it at target finalization,
as if \l qt_add_qml_preview() had been called on it explicitly. Executable
targets that are themselves QML modules created by \l qt_add_qml_module() are
unaffected, as they already get \l qmlpreview support from that command.
 
Setting this variable to a true value disables the automatic behavior for all
targets. This skips the small amount of extra configure-time work spent
creating a preview target for each executable, which is worthwhile for projects
that don't use \l qmlpreview, for example applications that only drive QML
through a \l QJSEngine for scripting, or release and CI builds where live reload
is irrelevant. Disable it for an entire build by passing
\badcode
-DQT_QML_NO_QML_PREVIEW=ON
\endcode
to the cmake executable, or set it in the project's \c CMakeLists.txt if preview
is never needed.
 
For finer control, individual targets can opt out with the
\l{cmake-target-property-QT_QML_NO_QML_PREVIEW}{QT_QML_NO_QML_PREVIEW}
property, or opt back in with \l qt_add_qml_preview() even when preview is
disabled globally.
 
\sa qt_add_qml_preview(), {cmake-target-property-QT_QML_NO_QML_PREVIEW}{QT_QML_NO_QML_PREVIEW}
\sa {Setting CMake variables and properties}
*/