qt_add_qml_preview

Sets up qmlpreview support for an executable that isn't itself a QML module.

This command was introduced in Qt 6.12.

The command is defined in the Qml component of the Qt6 package, which can be loaded like so:

find_package(Qt6 REQUIRED COMPONENTS Qml)

Synopsis

qt_add_qml_preview(target)

If versionless commands are disabled, use qt6_add_qml_preview() instead. It supports the same set of arguments as this command.

Description

qt_add_qml_preview() sets up qmlpreview live-reload support for an executable target that loads QML from one or more QML modules created with qt_add_qml_module(), but which is not itself created by qt_add_qml_module(). It creates an additional build target named <target>_qmlpreview that launches qmlpreview on the executable.

The target must be an executable target built by the current project. Passing a library target, or a target imported from another package, results in a configure-time error.

If target is itself a QML module, this command returns immediately without doing anything, because such targets already get qmlpreview support as part of qt_add_qml_module().

If target links against Qt6::Qml but no in-project QML modules can be found in its link closure, a warning is emitted at build time, because live reload of QML embedded in Qt resources will not work in that case. If this happens, link the qt_add_qml_module() target(s) whose QML files you want to preview to target.

By default, qmlpreview support is already set up automatically for every executable target that links against Qt6::Qml, so you normally don't need to call qt_add_qml_preview() at all. It is only useful as a per-target override when that automatic behavior has been switched off: calling it enables qmlpreview support for target even if preview has been disabled globally via the QT_QML_NO_QML_PREVIEW variable, or for that target via its QT_QML_NO_QML_PREVIEW property.

Example

qt_add_library(mylib STATIC)
qt_add_qml_module(mylib
    URI My.Lib
    VERSION 1.0
    QML_FILES
        Main.qml
)

qt_add_executable(myapp main.cpp)
target_link_libraries(myapp PRIVATE mylib)

qt_add_qml_preview(myapp)