QML Language Server | Qt Qml (original) (raw)

QML Language Server is a tool shipped with Qt that helps you write code in your favorite (LSP-supporting) editor. See Language Server Protocol for more information.

Currently, it enables your editor to:

• Autocomplete your code
• Display qmllint warnings
• Navigate to definitions in QML files
• Find usages of JavaScript variables and QML objects
• Rename JavaScript variables and QML objects
• Format QML files
• Get help from Qt Documentation

Note: qmlls is currently in development, see Known Limitations for more details.

Supported Features

Linting

QML Language Server can automatically lint opened QML files and display warnings or errors straight in the editor. See qmllint for more information about the linting process, and QML Lint Warning and Errors on how to fix warnings and errors.

Formatting

QML Language Server can format entire files from inside the editor. See qmlformat for more information about the formatting process.

Finding Definitions

QML Language Server can find definitions of JavaScript variables, functions, QML object id's and QML properties from their usages.

QML Language Server can also find the definition of types used in type annotations for JavaScript functions, QML object properties, and QML object instantiation.

Finding Usages

QML Language Server can find usages of JavaScript variables, QML object properties, JavaScript functions, QML object methods, and QML object id's.

Renaming

QML Language Server 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.

Suggesting Autocompletion Items

QML Language Server provides autocompletion suggestions for JavaScript variables, expressions, and statements, as well as QML object properties, methods, and id's.

Tracking Changes in C++ Files

QML Language Server 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 disable this feature.

Documentation Hints

QML Language Server 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 QT_QML_GENERATE_QMLLS_INI variable.

Setting up the QML Language Server in Your Editor

Note: You can find the QML Language Server binary under <Qt installation folder>/bin/qmlls in installations of Qt made with Qt Online Installer.

Setting up the Build Directory

QML Language Server needs to know the location of your build folder. You can pass it in the following ways:

• The --build-dir command line option. In this case your editor should invoke qmlls as following:
  <path/to/qmlls> ... --build-dir <path/to/build-directory> ...
• The QMLLS_BUILD_DIRS environment variable.
• The .qmlls.ini settings file, see Configuration File.

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.

Setting up the import paths

QML Language Server 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:

• The -I command line option. In this case your editor should invoke qmlls as following:
  <path/to/qmlls> ... -I /path/to/imports -I /optional/path/to/another/import ...
• The QML_IMPORT_PATH environment variable. In this case you should pass the -E option to QML Language Server.
• The .qmlls.ini settings file, see Configuration File.

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.

Setting up the documentation path

QML Language Server 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:

• The -d or -p command line option. In this case your editor should invoke qmlls as following:
  <path/to/qmlls> ... -d /path/to/docs ...
• The .qmlls.ini settings file, see Configuration File.

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.

Disabling 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:

• The --no-cmake-calls command line option. In this case your editor should invoke qmlls as follows:
  <path/to/qmlls> --build-dir <path/to/build-directory> --no-cmake-calls
• The QMLLS_NO_CMAKE_CALLS environment variable.
• The .qmlls.ini settings file, see Configuration File.

Configuration File

QML Language Server can be configured via a configuration file .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 should look like this:

// .qmlls.ini [General] buildDir=<path/to/build-directory> no-cmake-calls= docDir=<path/to/qt-documentation> importPaths=<path/to/imports>

Currently, the configuration file can be used to set the build directory of the current project and optionally disable the automatic CMake rebuild functionality for C++ defined QML types.

Note: QML Language Server can create default configuration files using the --write-defaults option. This will overwrite an already existing .qmlls.ini file in the current directory.

Known Limitations

Despite covering many common QML features, QML Language Server is still in development with some features yet to be supported:

• Suggesting autocompletions on invalid QML files.
• Navigating to definitions of objects defined in C++.
• Autocompleting context properties

QML Language Server might emit false positive warnings on projects

• using QMake or imperative type registration—see Port QML modules to CMake
• that were not built—QML Language Server uses the build information to find QML modules
• where QML modules don't follow the guidelines in Modern QML modules
• not using QT_QML_GENERATE_QMLLS_INI