VS Code for Qt Applications – Part 1 A Technical Guide

18.03.2020 Alessandro Ambrosano No comments

A few weeks ago, we published an article with an overview of Visual Studio Code through the eyes of a Qt developer.

In this short blog series, I will show you how to get up to speed with a Qt project using Visual Studio Code more in detail. Before digging into the Qt parts, I’d like to go through an overview of the bits and pieces that are needed to configure any C++ project.

Setup a workspace

With Visual Studio Code you can start hacking on your code pretty much right away, just by opening the folder where your code resides. Sometimes if you’re just skimming through a codebase and you just want to be able to look for specific strings on the whole project folder that is all you need.

You can also manage multiple folders at the same time on a single Visual Studio Code window, search for strings on all files on all folders, and if you set up your workspace properly, also cross navigate between files in different folders with the help of a C++ code model.

A Visual Studio Code workspace is just a bundle of opened folders

In any case, you can add a folder to your workspace by selecting the “File” menu and then “Add folder to workspace…”. Removing folders from a workspace is done by right clicking on a folder and then selecting “Remove Folder from Workspace”.

Doing anything more than just reading and searching through your code will require you to save and possibly adjust your workspace. Let’s start from saving your workspace. To do so, click on the “File” menu and select “Save Workspace As…”.

Once you have saved your workspace file, you can start editing it. That can be done through Visual Studio Code itself since it is basically a JSON file listing all folders belonging to the project and workspace level (that is, global) settings. If you have multiple folders, you may want to assign a name to each one as it might be helpful later on. To do so, edit the workspace file, and add a “name” attribute to the object relative to your folder, alongside the “path” attribute.

Get the right extensions

Putting the C++ developer hat on, other than just being able to search through your source code, you may also want some code model to be available, so that you can easily detect for instance wrong includes, typos in variables names and the like.

Visual Studio Code is language agnostic by nature, but lets you do this on C/C++ code bases by means of a C++ extension, which you can find in the marketplace under the unsurprising name “C/C++” (full extension identifier: ms-vscode.cpptools).

If you plan to use CMake in your projects, another handy extension is “CMake Tools” (ms-vscode.cmake-tools).

You can install them both as shown below, after opening the command list by pressing “Ctrl+Shift+P”.

Configuration files

Now that the workspace is configured we can finally go on and set up build configurations, run configurations and C++ specific settings. We will see these operations in detail below, but before doing that it’s worth spending a few extra words on some common concepts.

If you don’t have any configuration file yet, be it a run, build, or C++ settings file, Visual Studio Code will create them for you as soon as you try to update your configuration. By default, it will do so by creating a .vscode subfolder under your first workspace folder, and placing all your configuration files there. You can also choose to have one .vscode subfolder for each one of your workspace folders and add configuration files in each of them. This will let you adjust settings on a per-folder basis.

In all configuration files, you can use ${workspaceFolder} to refer to the current source code folder. It is important to keep in mind that ${workspaceFolder} will always refer to the workspace folder where the configuration files reside. If you want to access other workspace folders, you can do it by explicitly referring to their name in the workspace configuration file, so if the folder is named “folder1” in the workspace file, you can access it in the configuration file using ${workspaceFolder:folder1}.

Add and run build configurations

The first step to add a new build configuration is to open the command line (Ctrl+Shift+P) and select “Tasks: Run Task”. You will be prompted to create a “tasks.json” file if you don’t have one already. For a simple build task, just select “Others” for the task type. This will create an example “shell” build configuration which lets you run a command from your shell with a number of arguments.

From now on you can start setting up your build configurations as in the example below.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build target1",
      "type": "shell"
      "command": "make /f ${workspaceFolder:folder1}/Makefile target1"
      "options": {
        "cwd": "${workspace:folder1}"
      }
    }
    // ... add more tasks here
  ]
}

Once builds are configured Visual Studio code will allow you to:

• mark a run configuration as default (Ctrl+Shift+P -> “Tasks: Configure Default Build Task”)
• run a specific build configuration (Ctrl+Shift+P -> “Tasks: Run Task”, then select from the list of available build configurations)
• run the default build configuration (Ctrl+Shift+P -> “Tasks: Run Build Task” or just Ctrl+Shift+B)

How to use MSVC in a build configuration

When launching a build configuration on Windows, you will not have access to the MSVC compiler and all its associated environment variables by default. So if you try to run for instance nmake to build your project your build will fail.

This is usually solved by calling vcvarsall.bat (or its moral equivalent for later Visual Studio versions) before launching a build. We can’t do that straight away here because a shell run configuration command will be run through Windows’ PowerShell console and not through the classic command prompt, and vcvarsall.bat won’t run on PowerShell.

One way to fix this is to install the pscx module on your PowerShell. You can do it by running a PowerShell with administrator rights and typing:

Install-Module pscx

Once the module is installed you can run any batch file and retain the resulting environment by running Invoke-BatchFile. You can now use nmake (or any other MSVC binary) in a build configuration as in the example below:

{
  "label": "Build target1",
  "type": "shell"
  "command": "Invoke-BatchFile 'PATH_TO_YOUR_VCVARS' ; nmake /f ${workspaceFolder:folder1}/Makefile target1"
  "options": {
     "cwd": "${workspace:folder1}"
  }
}

Add and run launch configurations

The next step once your app is built is to add launch configuration(s) so you can debug (or just run) your executable(s).

First, let’s get Visual Studio Code to create a launch configuration file for you by opening the command line (Ctrl+Shift+P), selecting “Debug: Open launch.json”, and then “C++ (Windows)”. This will create a new launch.json configuration file. From there, it’s enough to update the “program” and “cwd” parameters on the autogenerated file to get a working configuration.

Once you’re done your launch configuration should look like this:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "target1",
      "type": "cppvsdbg",
      "request": "launch",
      "program": "${workspaceFolder:folder1}/build/target1",
      "args": [],
      "stopAtEntry": false,
      "cwd": "${workspaceFolder:folder1}/build",
      "environment": []
    }
    // ... add more targets here
  ]
}

Similarly to what happens with the build configuration file, you can add a new launch configurations by adding a new JSON object under the “configurations” list.

Once this is done, you can see a list of run configurations on the debug tab, which you can access by clicking on the small bug on the left side of the window or by pressing “Ctrl+Shift+D” on windows.

Workspace level configurations

All the build and run configurations we saw until now can also be set at a workspace level. This could be useful, for instance, if you want to access the same folder from multiple workspaces and different build configurations depending on the workspace.

The syntax is the same as for the folder level configuration files, you just have to put all the settings in your workspace file as in the following example:

{
  "folders": [ .... ],
  "settings": [ .... ],
  "tasks": [
    { ... first build conf ... },
    { ... second build conf ... }
  ],
  "launch": [
    { ... first run conf ... },
    { ... second run conf ... }
  ]
}

Set up the code model

With the steps described up to now, it will be possible to navigate across all files within the project which is currently opened inside the editor. It will also be possible to use code completion (IntelliSense) for all the types inside said project.

But what if your project is using third party libraries (say, Qt) and you want to be able to navigate to library headers and have code completion for library types (say, QObject, or QWidget)?

This can be configured thanks to the C/C++ extension installed before. To get it to work, we need to edit the configuration file for this extension by going to the command prompt (Ctrl+Shift+P) and selecting “C/C++: Edit configurations (JSON)”.

This is what the default configuration will look like on Windows:

{
    "configurations": [
        {
            "name": "Win32",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": [
                "_DEBUG",
                "UNICODE",
                "_UNICODE"
            ],
            "windowsSdkVersion": "10.0.17763.0",
            "compilerPath": "C:/Program Files (x86)/Microsoft Visual Studio/2019/Professional/VC/Tools/MSVC/14.22.27905/bin/Hostx64/x64/cl.exe",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "intelliSenseMode": "msvc-x64"
        }
    ],
    "version": 4
}

Here it is possible to tweak with the C and C++ standard versions (cStandard and cppStandard), but the most important fields if you want to include third party libraries to the code model properly are includePath and defines.

includePath is a JSON list and will tell the code model builder where to look for header files, so, for instance, if you are using Qt in your project, you will need to add something like “C:/Qt/5.12.7/msvc2017_64/include/**”. Note the trailing **, that tells the code model to look for headers in all the subfolders.

defines is a list that will tell the code model builder which preprocessor defines to use for building the code model. They should ideally reflect the ones that will be used at build time, as the C/C++ plugin can’t infer them from build tasks.

This concludes the first round of notes about using Visual Studio Code in your C++/Qt projects. It includes all the fundamental pieces and should be enough to get started using Visual Studio Code effectively. In the next posts I will go more into details on how to add Qt, qmake and cmake to the scene.

If you’re interested in learning more, you may want to read Part 2 of this blog series.