Nativs4Qt - Install natvis files for Qt

This repository contains:

• Up to date natvis files for Qt5 and Qt6
• Command line tool to install or update them in different locations

Installation

natvis4qt is a simple command line tool to install or update the natvis files in different locations.

[!CAUTION] The tool is in early stage, for now it can only overwrite natvis file in known locations. More later!

Installation via Scoop (preferred)

scoop bucket add narnaud https://github.com/narnaud/scoop-bucket
scoop install natvis4qt

Installation via Cargo

cargo install natvis4qt

Or via archive files

1. Go to the Releases page
2. Download the latest natvis-x86_64-pc-windows-msvc.zip file
3. Extract the files from it into a directory.

Usage

Just run natvis4qt install on the command line and follow the instructions.

The application is using different commands:

• install Install the natvis files in known directories (MSVC and Qt)
• update Update the natvis files
• set Adjust natvis4qt's settings

Integration

Visual Studio

Select a version of Visual Studio when installing the natvis files.

This will install the natvis files in a central place that is used by Visual Studio. See documentation here: Natvis file locations

Some visulaizers require debug symbols for Qt to be loaded. To load them, add the bin directory of your Qt installation (e.g. C:\Qt\6.8.0\msvc2022_64\bin) to the symbol search path under Options > Debugging > Symbols.

[!CAUTION] The Qt VS Addin must be deactivated, as it is silently overwriting the natvis files in the Visualizers directory, see QTVSADDINBUG-1308.

Image Watch

It is possible to visualize QImage and QPixmap using the Image Watch extension from Microsoft.

Install the extension, and click on the "View" button. It will open a new window with the image.

[!WARNING]

• it only supports image in RGB(A) with 32bits/pixel,
• the Qt natvis file must to be in the default Natvis file locations.

Visual Studio Code

Central Natvis file locations

Select VS Code C/C++ Extension when installing the natvis files.

This will install the natvis files in a central place that is used by Visual Studio. See available "documentation" here: Natvis file locations.

[!WARNING] The files may disappear after an update of the Microsoft C/C++ extension.

Per-project vizualizer file

Another option is to install the natvis files int eh different Qt directories, and set a visualizerFile to your launch configuration. Edit your launch.json file (or the launch section of your *.code-workspace file) and add something like that:

    "configurations": [
        {
            "name": "Current Target (VS)",
            "type": "cppvsdbg",
            "request": "launch",
            "program": "${command:cmake.launchTargetPath}",
            "visualizerFile": "${env:QTDIR}/natvis/qt6.natvis",
            "cwd": "${workspaceFolder}",
            "sourceFileMap": {
                "C:/work/build/qt5_workdir/w/s": "${env:QTDIR}/../Src",
                "Q:/qt5_workdir/w/s": "${env:QTDIR}/../Src",
                "C:/Users/qt/work/install": "${env:QTDIR}/../Src",
                "C:/Users/qt/work/qt": "${env:QTDIR}/../Src"
            },
            "symbolOptions": {
                "searchPaths": ["${env:QTDIR}/bin"],
            }
        }
    ]

[!IMPORTANT]

• The QTDIR environment variable must be set up before launching VS Code
• You are limited to only one vizualizer file with cppvsdbg, see related issue.

Update

If you have installed natvis4qt using scoop, installed Natvis files will be automatically updated when updating via scoop. If you don't want this mechanism, run:

natvis4qt set --autoupdate false

To update them by hand, just run:

natvis4qt update

Natvis files

If you are only interested in natvis files, you can find them here:

• qt5.natvis
• qt6.natvis

You can find the current support of the Natvis file here: SUPPORT.md

License

The natvis4qt tool is licensed under the MIT license.

The natvis files are also licensed under the MIT license.

Contributions

qt5.natvis:

• The Qt Company

qt6.natvis:

• The Qt Company
• Klarälvdalens Datakonsult AB (KDAB)
• @nerixyz
• @nholthaus
• @aleksey-nikolaev