https://github.com/narnaud/natvis4qt
Updated natvis files and cli tool to install them in different locations
https://github.com/narnaud/natvis4qt
cli natvis qt qt5 qt6 rust
Last synced: 3 months ago
JSON representation
Updated natvis files and cli tool to install them in different locations
- Host: GitHub
- URL: https://github.com/narnaud/natvis4qt
- Owner: narnaud
- License: mit
- Created: 2023-02-16T18:40:34.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-07T06:24:57.000Z (about 1 year ago)
- Last Synced: 2025-04-07T07:27:47.166Z (about 1 year ago)
- Topics: cli, natvis, qt, qt5, qt6, rust
- Language: Rust
- Homepage:
- Size: 776 KB
- Stars: 10
- Watchers: 2
- Forks: 1
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Support: SUPPORT.md
Awesome Lists containing this project
README
# 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](https://scoop.sh/) (preferred)
```batch
scoop bucket add narnaud https://github.com/narnaud/scoop-bucket
scoop install natvis4qt
```
### Installation via [Cargo](https://doc.rust-lang.org/cargo/)
```
cargo install natvis4qt
```
### Or via archive files
1. Go to the [Releases](https://github.com/narnaud/natvis4qt/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.
```
Usage: natvis4qt.exe [OPTIONS]
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](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2022#BKMK_natvis_location)
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](https://bugreports.qt.io/browse/QTVSADDINBUG-1308).
#### Image Watch
It is possible to visualize `QImage` and `QPixmap` using the [Image Watch](https://learn.microsoft.com/en-us/previous-versions/visualstudio/visual-studio-2015/debugger/image-watch/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 images in RGB(A) with 32 bits/pixel.
> - The Qt natvis file must be in the default [Natvis file locations](https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2022#BKMK_natvis_location).
### 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](https://github.com/microsoft/vscode-cpptools/issues/925#issuecomment-591483777).
> [!WARNING]
> The files may disappear after an update of the [Microsoft C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools).
#### 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:
```json
"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](https://github.com/microsoft/vscode-cpptools/issues/10917).
## 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:
```cmd
natvis4qt set --autoupdate false
```
To update them by hand, just run:
```cmd
natvis4qt update
```
## Natvis files
If you are only interested in natvis files, you can find them here:
- [qt5.natvis](https://github.com/narnaud/natvis4qt/blob/main/natvis/qt5.natvis)
- [qt6.natvis](https://github.com/narnaud/natvis4qt/blob/main/natvis/qt6.natvis)
You can find the current support of the Natvis file here: [SUPPORT.md](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](https://www.qt.io/)
`qt6.natvis`:
- [The Qt Company](https://www.qt.io/)
- [Klarälvdalens Datakonsult AB (KDAB)](https://www.kdab.com/)
- [@nerixyz](https://github.com/Nerixyz)
- [@nholthaus](https://github.com/nholthaus)
- [@aleksey-nikolaev](https://github.com/aleksey-nikolaev)