QML Language Server

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

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 QML Language Server in Your Editor

This section describes how to develop the QML Language Server client or how to use your own QML Language Server client.

You can find the QML Language Server binary under <Qt installation folder>/bin/qmlls in installations of Qt made with Qt Online Installer. If you want your QML Language Server client to download the binary directly, you can download the standalone version from github via https://github.com/TheQtCompanyRnD/qmlls-workflow/releases or https://qtccache.qt.io/QMLLS/LatestRelease.

Setting up the Build Directory

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

AddBuildDirs LSP Extension

To pass build directories via the LSP extension, send a notification to QML Language Server for the $/addBuildDirs method. $/addBuildDirs accepts one parameter of the form:

interface AddBuildDirsParams {
    buildDirsToSet: UriToBuildDirs[];
}

where UriToBuildDirs contains a workspace URI and a list of build directories. The workspace URI must designate a workspace advertised to QML Language Server via workspaceFolders or didChangeWorkspaceFolders. The build directories are file paths, not URIs.

interface UriToBuildDirs {
    baseUri: URI;
    buildDirs: string[];
}

–build-dir Command Line Option

If you don't need to support multiple workspaces, you can pass the build directories via 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 build directory will be applied to all workspaces if you use multiple workspaces in the same QML Language Server. The values from addBuildDirsMethod have higher precedence than the command line option.

QMLLS_BUILD_DIRS Environment Variable

You can also pass the build directories via the QMLLS_BUILD_DIRS environment variable. The build directory will be applied to all workspaces if you use multiple workspaces in the same QML Language Server. The values from --build-dir have higher precedence than the environment variable.

.qmlls.ini Settings File

If you can't pass the build directories using one of the previous options, you could try passing build directories to QML Language Server via a configuration file. See also Configuration File. The values from the settings file have lower precedence than --build-dir, QMLLS_BUILD_DIRS, and addBuildDirsMethod.

Configuring Automatic CMake Builds

QML Language Server 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.
• The QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS CMake variable if QT_QML_GENERATE_QMLLS_INI is enabled.

To control the number of jobs used by CMake, use

• The --cmake-jobs command line option. In this case your editor should invoke qmlls as follows:

  <path/to/qmlls> --build-dir <path/to/build-directory> --cmake-jobs <jobs>

• The QMLLS_CMAKE_JOBS environment variable.
• The .qmlls.ini settings file, see Configuration File.

Accepted values are integers greater than 0 and max to use all available cores.

Modifying the maximum amount of files to search

QML Language Server 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 QMLLS_MAX_FILES_TO_SEARCH environment variable. 0 disables the file searching feature, 20000 is the default value.

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 can have the following entries:

// .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

To use the configuration file to disable the automatic CMake rebuild functionality, set no-cmake-calls to true.

To control the number of jobs used by automatic CMake rebuilds, set the CMakeJobs value.

To support clients that can't pass the build directory to QML Language Server, as described in Setting up the Build Directory, set the buildDir value or let CMake generate the .qmlls.ini via QT_QML_GENERATE_QMLLS_INI.

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