Qt 6 Debugging in Visual Studio and VS Code

Show More Qt Value Types in the Debugger

Nicolas Arnaud-Cormos

9 March 2023

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.

About KDAB

Trusted software excellence across embedded and desktop platforms

The KDAB Group is a globally recognized provider for software consulting, development and training, specializing in embedded devices and complex cross-platform desktop applications. In addition to being leading experts in Qt, C++ and 3D technologies for over two decades, KDAB provides deep expertise across the stack, including Linux, Rust and modern UI frameworks. With 100+ employees from 20 countries and offices in Sweden, Germany, USA, France and UK, we serve clients around the world.

4 Comments

Let's be honest, debugging in QtCreator for Windows is a real pain.

Nice. Thank you. Any chance to mainline this?

The goal is indeed to push it upstream, I didn't have time yet. Please note that upstream you have ##NAMESPACE##::, while the version here doesn't (so it can be usable as is, while the upstream version is pre-processed by the plugin).

Debug QT on VSCODE
————————————————
click on RunAndDebug
Open the terminal window in VSCode
Goto Debug console

VSCode->Debug console
P qStr.toStdString()

Nicolas Arnaud-Cormos

Senior Software Engineer & Teamlead

Senior software engineer and teamlead at KDAB, Nicolas has actively developed with Qt since 2001 and is a founding member of Qtfr, the French Qt community site. He has worked on multiple Qt widgets or QML projects, with a particular emphasis on API design and software architecture. He has held Qt training classes for companies such as Michelin, Ford and ST-Ericsson. Nicolas holds an MSc in Computer Science.