From 53708b055c7ba581928abfdd4c660b2238eb7721 Mon Sep 17 00:00:00 2001 From: Sami Shalayel Date: Tue, 20 Jun 2023 16:41:27 +0200 Subject: [PATCH] doc: add a page for qmlls Add a page for qmlls and refer it from the QtQuick tools page. Explain what qmlls is, what is can do, how it needs to be setup and its known limitations. Fixes: QTBUG-113269 Fixes: QTBUG-114474 Change-Id: Ie7da7f47bf6914f3dde86fa976e8e70636b5565b Reviewed-by: Ulf Hermann Reviewed-by: Leena Miettinen Reviewed-by: Semih Yavuz (cherry picked from commit 3915ce12103c1dc9b6424f2210f30affb51fcfc4) Reviewed-by: Qt Cherry-pick Bot --- .../src/guidelines/qtquick-tool-qmlls.qdoc | 121 ++++++++++++++++++ .../guidelines/qtquick-toolsnutilities.qdoc | 6 + 2 files changed, 127 insertions(+) create mode 100644 src/quick/doc/src/guidelines/qtquick-tool-qmlls.qdoc diff --git a/src/quick/doc/src/guidelines/qtquick-tool-qmlls.qdoc b/src/quick/doc/src/guidelines/qtquick-tool-qmlls.qdoc new file mode 100644 index 0000000000..4412a0c7c0 --- /dev/null +++ b/src/quick/doc/src/guidelines/qtquick-tool-qmlls.qdoc @@ -0,0 +1,121 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! +\page qtquick-tool-qmlls.html +\title QML Language Server +\brief Overview of the QML Language Server (qmlls). + +QML Language Server 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 Format QML files +\endlist + +\note qmlls is currently in development, see \l{Known Limitations} for +more details. + +\section1 Supported Features + +\section2 Linting + +QML Language Server 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. + +\section2 Formatting + +QML Language Server can format entire files from inside +the editor. See \l{qmlformat} for more information about the +formatting process. + + +\section2 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. + +\section2 Finding Usages + +QML Language Server can find usages of JavaScript variables, +QML object properties, JavaScript functions, QML object methods, +and QML object id's. + +\section1 Setting up the QML Language Server in Your Editor + +\note You can find the QML Language Server binary under +\c{/bin/qmlls}. + +QML Language Server also needs to know the location of your build +folder. You can pass it the following ways: +\list + \li The \c{--build-dir} command line option. In this case +your editor should invoke \c{qmlls} as following: +\badcode + --build-dir +\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. + +\section1 Configuration File + +QML Language Server 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 should look like this: +\code +// .qmlls.ini +[General] +buildDir= +\endcode + +Currently, the configuration file can only be used to set the build +directory of the current project. + +\note QML Language Server 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 + +QML Language Server might emit false positive warnings on projects +that were not built, as it needs the build information to find +QML modules defined in the same project, for example. + +Despite covering many common QML features, +the QML Language Server is still in development with some features +yet to be supported: + +\list + \li Renaming symbols (JavaScript variables, QML object id's, QML +object properties, and so on). + \li Formatting only parts of a document. + \li Formatting using a configurable set of rules. + \li Navigating to definitions of objects defined in C++. +\endlist + +The QML code model in the QML Language Server does not yet +support all of the JavaScript language constructs, which means that +some features like navigating to definition and finding usages might not +work on these language constructs. + + +*/ diff --git a/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc b/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc index 8719c78b30..ed1d84ac23 100644 --- a/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc +++ b/src/quick/doc/src/guidelines/qtquick-toolsnutilities.qdoc @@ -107,4 +107,10 @@ The Qt Quick Compiler consist of two components: \li \l {QML type compiler} \li \l {QML script compiler} \endlist + +\section1 QML Language Server + +\l{QML Language Server} is a tool shipped with Qt that helps you edit +QML code in your favorite (LSP-compatible) editor. + */