Qt 6 Debugging in Visual Studio and VS Code Show More Qt Value Types in the Debugger

09.03.2023 Nicolas Arnaud-Cormos 4 comments

Not all Qt developers are using Qt Creator as their main IDE for development. Some of us are using other IDEs, like Visual Studio, Visual Studio Code or CLion, per choice or because a project requires it.

On Windows, with the MSVC compiler, the debugging experience with Qt 6 can be quite frustrating for some Qt types, like QMap, QHash or QVariant. See, for example, the debug variable view for the same project running with Qt Creator (left) and Visual Studio Code (right):

I don’t know about you, but for me the VS Code view is gibberish. It was way better with Qt 5, as seen below:

Let’s see how to improve things…

Use the Natvis Framework

The Natvis framework allows developers to write custom schemas to help visualize native objects. This is already used by the Qt VS Tools for Visual Studio, with Qt 5 and a Qt 6 specific files. You can download the official Qt natvis files here: Qt VS Tool github.

They are pre-processed and copied automatically by the plugin to %HOME%\Documents\Visual Studio 2022\Visualizers. If you want to use them directly from github, make sure to remove all occurrences of ##NAMESPACE##::.

If you look closely at the size of the file, you can see that the Qt 5 Natvis file is 40.9 KB. The Qt 6 Natvis file is only 18.5 KB, which is not 50% smaller than the Qt 5 — au contraire! This means that a lot of types are not working anymore, most likely because the Qt 5 implementation didn’t work during the migration to Qt 6 due to changes in the underlying data.

Let’s see how far we can improve things here. This blog won’t be about the how (it involved a lot of cursing…), but only about the improvements made to the qt6.natvis file.

Changes

For developers in a hurry, you can download the updated Natvis file here:

https://github.com/KDAB/KDToolBox/blob/master/qt/qt6_natvis/qt6.natvis

QMap Improvements

QMap was already working, but I wanted a nicer view, with [key]: value display.

QHash Improvements

QHash was the very reason I started the journey; I just wanted to see something, ideally, like QMap. Unfortunately, it’s not supported on CLion, which is missing support for the CustomListItems Natvis tag.

QMultiHash Improvements

Once QHash was done, QMultiHash was quite easy. Please note that the view is slightly different from the std::unordered_map equivalent; the Qt version is showing a list of values for one key, while the std version shows a list of (key, value) pairs with duplicated keys. Like QHash, QMultiHash view is not supported in CLion.

QVariant Improvements

After looking at the containers, I decided to look at QVariant. Unfortunately, not all types are properly handled, but at least the static primitives, core templates, and most of the core classes are. If the type is unknown, it will show at least the typeId, so the developer can know what is inside the QVariant. The full list is available here: Qt6 Natvis documentation

How to Use this New qt6.natvis File

Visual Studio

Follow the instructions here to add a natvis file to your project: Add a .natvis file to a C++ project.

VS Code

We already discussed it in another blog post: VS Code for Qt Applications – Part 2. Just a quick recap:

• create a launch.json file (that’s the “Debug: Add Configuration…” command)
• Set the visualizerFile property to the qt6.natvis file

This is an example launch.json file that works well with CMake project:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "qt6.4.2-msvc",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${command:cmake.launchTargetPath}",
            "visualizerFile": "${workspaceFolder}/qt6.natvis",
            "sourceFileMap": {
                "C:/work/build/qt5_workdir/w/s": "C:/Qt/6.4.2/Src",
                "Q:/qt5_workdir/w/s": "C:/Qt/6.4.2/Src",
                "C:/Users/qt/work/install": "C:/Qt/6.4.2/Src",
                "C:/Users/qt/work/qt": "C:/Qt/6.4.2/Src"
            }
        }
    ]
}

Why Not Do the Same As Qt Creator?

That’s a good question, and my first attempt at trying to fix this issue was to look at Qt Creator. After all, it’s using the same compiler and debugger. Surely, I can find something I can use. Quoting the documentation:

Qt Creator extends the command line debugger by loading the qtcreatorcdbext.dll extension library into it. The library must be available in the libs\qtcreatorcdbext64 and libs\qtcreatorcdbext32 folder. To install it there, select Qt Creator CDB Debugger Support when you install Qt Creator.

Again, quoting the documentation:

Qt Creator uses Python scripts to translate raw memory contents and type information data from native debugger backends (GDB, LLDB, and CDB are currently supported) into the form presented to the user in the Locals and Expressions views.

That’s the reason why the debugger is slower in Qt Creator (you can disable it from the Debugger->CDB preference page, with the “Use Python dumper” option). Unfortunately, it’s not usable for Visual Studio and VS Code.

Conclusion

It’s unfortunately impossible to go as far as what Qt Creator can do, but the changes to the qt6.natvis file improve the debugging experience quite a lot already, and we are close to feature parity with qt5.natvis. The file is part of our KDToolBox project. KDToolBox is a collection of useful code, scripts and snippets you are free to use; you can download it here:

https://github.com/KDAB/KDToolBox/blob/master/qt/qt6_natvis/qt6.natvis

This file can be used for Visual Studio, VS Code, and CLion IDEs, with the exception of QHash and QMutiHash not working with CLion. If something is missing, send me a note, no promises though.