Natvis4Qt - 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.

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

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

Usage

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

Demo

Usage: natvis4qt.exe [OPTIONS] <COMMAND>

Commands:
  install  Install the natvis files
  update   Update the natvis files
  set      Adjust natvis4qt's settings
  help     Print this message or the help of the given subcommand(s)

Options:
      --dry-run  Install or update without copying the files
  -h, --help     Print help (see more with '--help')
  -V, --version  Print version

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 visualizers 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.

Image Watch Example

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

[!WARNING]

It only supports images in RGB(A) with 32 bits/pixel.

The Qt natvis file must 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 the C/C++ extension. See available "documentation" here: Natvis file locations.

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

Per-project visualizer file

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

    "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 visualizer 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:

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:

Natvis4qt

Install / Use

README