6.8. Generation of IDE project configuration#

Here are the notes about how some IDE configuration works, and why we did generation one way or another.

6.8.1. CLion#

6.8.1.1. Toolchain#

Specifies the C and C++ compilers, cmake path, build tool path (ninja, make) and debugger path (gdb, lldb).
It is not project-specific, and so we do not want to configure a toolchain for each project - otherwise there will be a lot of them visible in selection list.

It can source a shell script to define environment. The environment is applied to everything: configure, build, and run/debug.

Cmake profiles (see below) name specific toolchain they use, so we ask user to create a toolchain named "KDE Builder Toolchain", and we use that name in cmake profile that we generate.

6.8.1.2. CMake Profiles#

CLion CMake profiles documentation

Defines toolchain name to use, cmake configure options, build directory, and environment variables.

The environment variables you specify in the profile affect CMake generation and build, but not the binary launch.

If project has CMakePresets.json, in CMake Profiles there will be read-only profiles shown based on presets. Thankfully, they are disabled by default, so we should not care of them.

Currently, it is not possible to source the script in cmake profiles. See this issue.

So we currently cannot just point to kde-builder.env. We inject each variable manually.

6.8.1.3. Run/Debug configuration#

CLion Run/debug configurations documentation

We replicate the behavior of kde-builder when using --run. KDE Builder launches from install directory, and sources prefix.sh from build directory and file from source-when-start-program option.

Currently, it is not possible to source several scripts, see this issue. And so, because the content of prefix.sh is predictable, we inject variables from there manually, and we point to the source-when-start-program file for sourcing.

The syntax of variables in JetBrains IDEs is limited, and currently does not support expansion like in shell, see this issue. So I currently just use all possible paths for such variables. I.e. for ${XDG_DATA_DIRS:-/usr/local/share/:/usr/share/} I use $XDG_DATA_DIRS$:/usr/local/share/:/usr/share/.

In the target, we select "All targets", because kde-builder does not specify a target when building, and this implicitly means all targets.

6.8.2. VS Code#

VS Code Cmake Tools documentation toc

6.8.2.1. Kit#

VS Code kits documentation

CMake kit can define compilers (c, c++, etc.), toolchain file.

Additionally, can define:

fallback generator
cmake configure options (but documentation asks to not use it for project specific options)
environment variables
environment script

IDE local kits are autogenerated (by scanning), and added manually (by specifying unique name).
Project-specific kits are defined in .vscode/cmake-kits.json

We do not specify a kit.

6.8.2.2. CMake variants#

VS Code CMake variants documentation

A CMake Tools extension feature, that allows to specify set of build options, and then combine them.

The project-specific file is called cmake-variants.json or cmake-variants.yaml.

It defines "variant settings" (for example, "buildType" and "useOpenGL"). Each variant setting has defined "options" (defined by "choices").
A combination of options, from a set of settings, forms a variant. A variant is a specific combination of one option from each setting.

Each setting option can define env variables and cmake options.

From my point of view, this is a very weird feature and is not wanted.

Originally, we wanted to generate a project specific cmake variants file, that specifies only one setting with only one choice - to not alter any cmake options, see here. But it was buggy at the moment we tried.

Sadly, the "Unspecified" option is not yet available in default options. So we do not have a way to create unaltered variant. For now, we will document this. Later we can recheck the situation, and possibly fix it.

Todo: check if the situation changed, and redocument as normal, if it normalized.

We do not specify variant settings.

6.8.2.3. Configure settings and environment#

The order in which they are determined is described here.

We inject variables used at cmake configure from kde-builder (including set-env variables from global and from module).

Despite documentation says cmake.environment is applied to launch/debug, this actually is wrong. See this mr.

So we use cmake.environment instead of cmake.configureEnvironment with cmake.buildEnvironment, to reduce duplication in the settings.json.

6.8.2.4. Build environment#

VS Code cmake build documentation

We inject variables used at cmake build from kde-builder (including set-env variables from global and from module).

6.8.2.5. Run/Debug environment#

VS Code debug/launch documentation

The environment is only constructed by environment in launch.json.
Currently, launch configuration does not support sourcing a file to set environment. See this issue.
The kit's environment from script also cannot be used, see here.

The one workaround is to use a pre-launch task that will make an env file (i.e. not a script), that can be pointed to in the launch.json.
The other workaround is to launch vscode from the terminal where the needed environment was already placed.
The third workaround is to avoid using a script, and specify the final values of variables either in env file or directly in launch.json.

We inject variables from prefix.sh from build dir, and also specify file from source-when-start-program in the envFile.

Todo: Check if that feature is implemented, and if it was, add to appropriate option instead of to envFile.

6.8.3. Qt Creator#

Here is documentation on how to make a shared configuration: https://doc.qt.io/qtcreator/creator-sharing-project-settings.html.

Unfortunately, I (Andrew Shark) had no success to generate the configuration from outside. The nearest I got is file in successfully importing configuration from file you can see in data/qtcreator/CMakeLists.txt.shared.in. I placed some variable in configure, build, and run, and also added a cmake option.

The problem currently is that such .shared file cannot be actually shared, because of the <value type="QString" key="ProjectExplorer.ProjectConfiguration.Id"> in Target configuration. Without that value tag, the .shared file is just ignored, so there is no sense to generate it in such way.

Instead, I generate the txt files under .qtcreator directory, from where the user can copy-paste text for cmake options and environment.

The full configuration guide will be in the develop.kde.org.

Here I will leave some useful info that could be used in case Qt Creator improves in the future.

6.8.3.1. Kit#

QT Creator Kits documentation
Qt Creator Activate kits for a project documentation

A kit is an IDE specific (i.e., not a project setting), and creation of it cannot be automated. So we ask user to define a kit manually.

In main menu, go to Edit -> Preferences. In the opened window, in the "Kits" category, go to "Kits" tab.

There is no way to not define a generator in kit, but it can be overriden by the cmake configuration.

The kit must have two cmake options:

-DCMAKE_C_COMPILER:FILEPATH=%{Compiler:Executable:C}
-DCMAKE_CXX_COMPILER:FILEPATH=%{Compiler:Executable:Cxx}

otherwise, it will have exclamation mark.

6.8.3.1.1. Qt version in kit#

Do we need to create a "Qt Version"? It seems no.
In my Arch Linux, the Qt 5 was autodetected, but not Qt 6. The page Opening Project says:

Even if you do not intend to build the project, the C++ and QML code models need a Qt version and compiler to offer code completion. To specify them, select the Preferences link, or select Preferences > Kits.

We can manually add /usr/bin/qmake6 path in "Qt Versions". But tooltip says that for systems not using qmake, this is optional.

6.8.3.1.2. Removing unwanted kits#

In case project has CMakePresets.json file, then when we open it, it will create many "temporary" kits. We do not need them, and can remove all of them. In case we want them in the future, we could do Build -> Reload CMake Presets.

Alternatively, we could keep them there in kits, but deactivate for the project/for all projects. If we accidentally clicked on an unwanted kit in "Build & Run", it got activated. To disable it again, click on its name with right mouse button, and select "Disable Kit for all projects". See screenshot from here.

6.8.3.2. Configuration documentation:#

6.8.3.4. Other notes#

Opening project. The "Import builds" function seems not very useful, because you anyway would not have the initial configuration (cmake options and enviroment).

Generation of IDE project configuration

Contents