1// Copyright (C) 2023 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtqml-tooling-qmlls.html
7\brief Overview of \QMLLS (qmlls).
10\QMLLS is a tool shipped with Qt that helps you write code
11in your favorite (LSP-supporting) editor.
12See \l{https://microsoft.github.io/language-server-protocol/}{Language Server Protocol}
15Currently, it enables your editor to:
17 \li Autocomplete your code
18 \li Display qmllint warnings
19 \li Navigate to definitions in QML files
20 \li Find usages of JavaScript variables and QML objects
21 \li Rename JavaScript variables and QML objects
25\note qmlls is currently in development, see \l{Known Limitations} for
28\section1 Supported Features
32\QMLLS can automatically lint opened QML files
33and display warnings or errors straight in the editor. See
34\l{qmllint Reference}{qmllint} for more information about the linting process.
38\QMLLS can format entire files from inside
39the editor. See \l{qmlformat} for more information about the
43\section2 Finding Definitions
45\QMLLS can find definitions of JavaScript variables,
46functions, QML object id's and QML properties from their usages.
48\QMLLS can also find the definition of types used in
49type annotations for JavaScript functions, QML object properties,
50and QML object instantiation.
52\section2 Finding Usages
54\QMLLS can find usages of JavaScript variables,
55QML object properties, JavaScript functions, QML object methods,
60\QMLLS can rename JavaScript variables and functions,
61as well as QML object properties, methods, and id's, as long as
62they are defined in a QML file.
64\section2 Suggesting Autocompletion Items
66\QMLLS provides autocompletion suggestions for
67JavaScript variables, expressions, and statements, as well as
68QML object properties, methods, and id's.
70\section2 Tracking Changes in C++ Files
72\QMLLS can track changes in C++ files defining QML
73types. It automatically rebuilds CMake QML modules to provide
74accurate and up-to-date warnings and completion items for C++
78\l{Disabling automatic CMake builds}{disable this feature}.
80\section1 Setting up the \QMLLS in Your Editor
82\note You can find the \QMLLS binary under
83\c{<Qt installation folder>/bin/qmlls} in installations of Qt
86\section2 Setting up the Build Directory
88\QMLLS needs to know the location of your build
89folder. You can pass it the following ways:
91 \li The \c{--build-dir} command line option. In this case
92your editor should invoke \c{qmlls} as following:
94<path/to/qmlls> --build-dir <path/to/build-directory>
96 \li The \c{QMLLS_BUILD_DIRS} environment variable.
97 \li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
100\note When the build directory is specified in multiple ways, the
101command line option takes preference over the environment variable
102that takes precedence over the setting file.
104\section2 Disabling Automatic CMake Builds
106\c{qmlls} will try to trigger a CMake rebuild when it detects that the
107source code of a C++ defined QML type has been modified.
109To disable this feature, use the following ways:
111 \li The \c{--no-cmake-calls} command line option. In this case
112your editor should invoke \c{qmlls} as follows:
114<path/to/qmlls> --build-dir <path/to/build-directory> --no-cmake-calls
116 \li The \c{QMLLS_NO_CMAKE_CALLS} environment variable.
117 \li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
120\section1 Configuration File
122\QMLLS can be configured via a configuration file \c{.qmlls.ini}.
123This file should be in the root source directory of the project.
124It should be a text file in the ini-format.
126\note \c{.qmlls.ini} files can be generated automatically via
127\l{QT_QML_GENERATE_QMLLS_INI}.
129The configuration file should look like this:
133buildDir=<path/to/build-directory>
134no-cmake-calls=<true-or-false>
137Currently, the configuration file can be used to set the build
138directory of the current project and optionally disable the automatic
139CMake rebuild functionality for C++ defined QML types.
141\note \QMLLS can create default configuration files
142using the \c{--write-defaults} option. This will overwrite an
143already existing .qmlls.ini file in the current directory.
145\section1 Known Limitations
147\QMLLS might emit false positive warnings on projects
148that were not built, as it needs the build information to find
149QML modules defined in the same project, for example.
151Despite covering many common QML features,
152the \QMLLS is still in development with some features
156 \li Renaming QML types.
157 \li Suggesting autocompletions on invalid QML files.
158 \li Navigating to definitions of objects defined in C++.
159 \li Supporting all QML and JavaScript language constructs for all features.
162The QML code model in the \QMLLS does not yet
163support all of the JavaScript language constructs, which means that
164some features like navigating to definition and finding usages might not
165work on these language constructs.