1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
|
// Copyright (C) 2023 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\page qtqml-tooling-qmlls.html
\title \QMLLS
\keyword \QMLLS Reference
\brief A tool that helps you write code in your favorite LSP-supporting editor.
\ingroup qtqml-tooling
\ingroup qtqml-tooling-devtools
\QMLLS is a tool shipped with Qt that helps you write code
in your favorite (LSP-supporting) editor.
See \l{https://microsoft.github.io/language-server-protocol/}{Language Server Protocol}
for more information.
Currently, it enables your editor to:
\list
\li Autocomplete your code
\li Display qmllint warnings
\li Navigate to definitions in QML files
\li Find usages of JavaScript variables and QML objects
\li Rename JavaScript variables and QML objects
\li Format QML files
\li Get help from Qt Documentation
\endlist
\note \c qmlls is currently in development, see
\l{#Known Limitations}{Known Limitations} for more details.
\section1 Supported Features
\section2 Linting
\QMLLS can automatically lint opened QML files
and display warnings or errors straight in the editor. See
\l{qmllint} for more information about the linting process,
and \l{QML Lint Warning and Errors} on how to fix warnings and
errors.
\section2 Formatting
\QMLLS can format entire files from inside
the editor. See \l{qmlformat} for more information about the
formatting process.
\section2 Finding Definitions
\QMLLS can find definitions of JavaScript variables,
functions, QML object id's and QML properties from their usages.
\QMLLS can also find the definition of types used in
type annotations for JavaScript functions, QML object properties,
and QML object instantiation.
\section2 Finding Usages
\QMLLS can find usages of JavaScript variables,
QML object properties, JavaScript functions, QML object methods,
and QML object id's.
\section2 Renaming
\QMLLS can rename JavaScript variables and functions,
as well as QML object properties, methods, and id's, as long as
they are defined in a QML file.
\section2 Suggesting Autocompletion Items
\QMLLS provides autocompletion suggestions for
JavaScript variables, expressions, and statements, as well as
QML object properties, methods, and id's.
\section2 Tracking Changes in C++ Files
\QMLLS can track changes in C++ files defining QML
types. It automatically rebuilds CMake QML modules to provide
accurate and up-to-date warnings and completion items for C++
defined QML types.
You can
\l{Disabling automatic CMake builds}{disable this feature}.
\section2 Documentation Hints
\QMLLS includes a documentation hints feature that
provides programmers with quick access to Qt’s documentation
by hovering over a keyword. In order to use this feature, your
Qt kit should contain the Qt documentation and your project
should be built with \l{QT_QML_GENERATE_QMLLS_INI} variable.
\section1 Setting up the \QMLLS in Your Editor
\note You can find the \QMLLS binary under
\c{<Qt installation folder>/bin/qmlls} in installations of Qt
made with \QOI.
\section2 Setting up the Build Directory
\QMLLS needs to know the location of your build
folder. You can pass it in the following ways:
\list
\li The \c{--build-dir} command line option. In this case
your editor should invoke \c{qmlls} as following:
\badcode
<path/to/qmlls> ... --build-dir <path/to/build-directory> ...
\endcode
\li The \c{QMLLS_BUILD_DIRS} environment variable.
\li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
\endlist
\note When the build directory is specified in multiple ways, the
command line option takes preference over the environment variable
that takes precedence over the setting file.
\section2 Setting up the import paths
\QMLLS needs to know the import paths of the Qt version that you
are using in your project. You can pass the import paths in the
following ways:
\list
\li The \c{-I} command line option. In this case
your editor should invoke \c{qmlls} as following:
\badcode
<path/to/qmlls> ... -I /path/to/imports -I /optional/path/to/another/import ...
\endcode
\li The \c{QML_IMPORT_PATH} environment variable. In this case you
should pass the \c{-E} option to \QMLLS.
\li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
\endlist
\note When the import path is specified in multiple ways, the
command line option takes preference over the environment variable
that takes precedence over the setting file.
\section2 Setting up the documentation path
\QMLLS can show documentation hints when it knows the documentation
path of the Qt version that you are using in your project. You can pass
the documentation path in the following ways:
\list
\li The \c{-d} or \c{-p} command line option. In this case
your editor should invoke \c{qmlls} as following:
\badcode
<path/to/qmlls> ... -d /path/to/docs ...
\endcode
\li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
\endlist
\note When the documentation path is specified in multiple ways, the
command line option takes preference over the environment variable
that takes precedence over the setting file.
\section2 Configuring Automatic CMake Builds
\QMLLS will try to trigger a CMake rebuild when it detects that the
source code of a C++ defined QML type has been modified.
To disable this feature, use the following ways:
\list
\li The \c{--no-cmake-calls} command line option. In this case
your editor should invoke \c{qmlls} as follows:
\badcode
<path/to/qmlls> --build-dir <path/to/build-directory> --no-cmake-calls
\endcode
\li The \c{QMLLS_NO_CMAKE_CALLS} environment variable.
\li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
\li The \l{QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS} CMake variable.
\endlist
To control the number of jobs used by CMake, use
\list
\li The \c{--cmake-jobs} command line option. In this case
your editor should invoke \c{qmlls} as follows:
\badcode
<path/to/qmlls> --build-dir <path/to/build-directory> --cmake-jobs <jobs>
\endcode
\li The \c{QMLLS_CMAKE_JOBS} environment variable.
\li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
\endlist
Accepted values are integers greater than 0 and \c{max} to use all available
cores.
\section2 Modifying the maximum amount of files to search
\QMLLS respects a limit of files to search when searching the source
folders for headers, for example when going to the definition of a QML
component defined in a C++ header.
To set the maximum amount of files to search, write a numeric value in the
\c QMLLS_MAX_FILES_TO_SEARCH environment variable. 0 disables the file
searching feature, 20000 is the default value.
\section1 Configuration File
\QMLLS can be configured via a configuration file \c{.qmlls.ini}.
This file should be in the root source directory of the project.
It should be a text file in the ini-format.
The configuration file can have the following entries:
\code
// .qmlls.ini
[General]
no-cmake-calls=<true-or-false>
CMakeJobs=<some integer value>
buildDir=<path/to/build-directory> # not required in Qt 6.10 and later
docDir=<path/to/qt-documentation> # not required in Qt 6.10 and later
importPaths=<path/to/imports> # not required in Qt 6.10 and later
\endcode
To use the configuration file to disable the automatic CMake rebuild
functionality, set \c{no-cmake-calls} to \c{true}.
To control the number of jobs used by automatic CMake rebuilds, set the
CMakeJobs value.
\note \QMLLS can create default configuration files
using the \c{--write-defaults} option. This will overwrite an
already existing .qmlls.ini file in the current directory.
\section1 Known Limitations
Despite covering many common QML features, \QMLLS is still in development with some features
yet to be supported:
\list
\li Suggesting autocompletions on invalid QML files.
\li Navigating to definitions of objects defined in C++.
\li Autocompleting context properties
\endlist
\QMLLS might emit false positive warnings on projects
\list
\li using QMake or imperative type registration---see \l{Port QML modules to CMake}
\li that were not built---\QMLLS uses the build information to find QML modules
\li where QML modules don't follow the guidelines in \l{Modern QML modules}
\endlist
*/
|
