Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
qtqmlcompiler-index.qdoc
Go to the documentation of this file.
1// Copyright (C) 2023 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \page qtqmlcompiler-index.html
6 \title Qt Qml Compiler
7 \brief Provides tools for static analysis of QML code.
8
9 The Qt Qml Compiler module contains shared functionality needed by QML
10 tooling like the \l{Qt Quick Compiler} and \l{qmllint}.
11 It also provides the QQmlSA framework, which can be used to extend the
12 built-in analysis capabilities of the tools.
13
14 \section1 Using the Module
15
16 \include {module-use.qdocinc} {using the c++ api}
17
18 \section2 Building with CMake
19
20 \include {module-use.qdocinc} {building with cmake} {QmlCompiler}
21
22 \section2 Building with qmake
23
24 \include {module-use.qdocinc} {building_with_qmake} {QmlCompiler}
25
26 \section1 Using the QQmlSA framework
27
28 The Qt Qml Compiler module offers the QQmlSA framework which provides tools
29 for static analysis of QML code. These tools can help ensure syntactic
30 validity and warn about QML anti-patterns.
31
32 Adding static analysis to a QML program is done by writing plugins. They
33 will run a collection of analysis passes over the elements and properties
34 of the QML code. The passes can be registered with a PassManager which
35 holds the passes and can be called to analyze an element and its children.
36 A pass is a check for a certain rule or condition evaluated on elements or
37 properties. If the condition is met, the pass can warn the user of an
38 indentified issue in the code and maybe even suggest a fix. It is called a
39 pass because the analysis performed on elements and properties happens by
40 running a collection of passes on them in succesion. Each pass should be
41 responsible for identifying one specific issue only. Combining a set of
42 passes can perform more complex analysis and, together, form a plugin.
43 Element passes are defined by two main components, namely \c shouldRun()
44 and \c run(). When performing the analysis, the pass manager will execute
45 the pass over every element it encounters while traversing the children of
46 the root element. For each element, if \c shouldRun() evaluated on that
47 element returns \c true then \c run() is executed on it.
48
49 Passes on properties trigger on three different events, namely when the
50 property is bound, when it is read, and when it is written to. These can be
51 implemented by overriding the \c onBinding(), \c onRead() and \c onWrite()
52 functions respectively.
53
54 As the code grows, so does the number of elements and properties.
55 Performing the static analysis passes on all of them can become expensive.
56 That's why it is good to be granular when deciding which elements and
57 properties to analyze. For elements, the \c shouldRun() is intended to be a
58 cheap check to determine if \c run(), which performs the real computation,
59 should be run. For properties, the selection is done when registering the
60 passes with the manager. The \c registerPropertyPass() function takes the
61 \c moduleName, \c typeName and \c propertyName strings as arguments. These
62 are used to filter down the set of properties affected by the registered
63 pass.
64
65
66 \section1 Examples
67
68 The \l{QML Static Analysis Tutorial} shows how to use the \c{QQmlSA}
69 framework to create a custom \l{qmllint} pass.
70
71 \section1 Reference
72
73 \list
74 \li \l {Qt Qml Compiler C++ Classes}
75 - the C++ API provided by the QmlCompiler module
76 \li QML tooling using the static analysis capabilities
77 \list
78 \li \l{QML script compiler}
79 \li \l{qmllint}
80 \li \l{\QMLLS}
81 \li \l{QML type compiler}
82 \endlist
83 \endlist
84 */