Qt QML Compiler

The Qt QML Compiler module contains shared functionality needed by QML tooling like the Qt Quick Compiler and qmllint. It also provides the QQmlSA framework, which can be used to extend the built-in analysis capabilities of the tools.

Using the Module

Using a Qt module's C++ API requires linking against the module library, either directly or through other dependencies. Several build tools have dedicated support for this, including CMake and qmake.

Building with CMake

Use the find_package() command to locate the needed module component in the Qt6 package:

find_package(Qt6 REQUIRED COMPONENTS QmlCompiler)
target_link_libraries(mytarget PRIVATE Qt6::QmlCompiler)

For more details, see the Build with CMake overview.

Building with qmake

To configure the module for building with qmake, add the module as a value of the QT variable in the project's .pro file:

QT += QmlCompiler

Using the QQmlSA framework

The Qt QML Compiler module offers the QQmlSA framework which provides tools for static analysis of QML code. These tools can help ensure syntactic validity and warn about QML anti-patterns.

Adding static analysis to a QML program is done by writing plugins. They will run a collection of analysis passes over the elements and properties of the QML code. The passes can be registered with a PassManager which holds the passes and can be called to analyze an element and its children. A pass is a check for a certain rule or condition evaluated on elements or properties. If the condition is met, the pass can warn the user of an indentified issue in the code and maybe even suggest a fix. It is called a pass because the analysis performed on elements and properties happens by running a collection of passes on them in succesion. Each pass should be responsible for identifying one specific issue only. Combining a set of passes can perform more complex analysis and, together, form a plugin. Element passes are defined by two main components, namely shouldRun() and run(). When performing the analysis, the pass manager will execute the pass over every element it encounters while traversing the children of the root element. For each element, if shouldRun() evaluated on that element returns true then run() is executed on it.

Passes on properties trigger on three different events, namely when the property is bound, when it is read, and when it is written to. These can be implemented by overriding the onBinding(), onRead() and onWrite() functions respectively.

As the code grows, so does the number of elements and properties. Performing the static analysis passes on all of them can become expensive. That's why it is good to be granular when deciding which elements and properties to analyze. For elements, the shouldRun() is intended to be a cheap check to determine if run(), which performs the real computation, should be run. For properties, the selection is done when registering the passes with the manager. The registerPropertyPass() function takes the moduleName, typeName and propertyName strings as arguments. These are used to filter down the set of properties affected by the registered pass.

Examples

The QML Static Analysis Tutorial shows how to use the QQmlSA framework to create a custom qmllint pass.

Reference

• Qt QML Compiler C++ Classes - the C++ API provided by the QmlCompiler module
• QML tooling using the static analysis capabilities
  • QML script compiler
  • qmllint
  • QML Language Server
  • QML type compiler