Building and Debugging

This document consolidates all instructions for building the NVIGI SDK and for debugging the resulting binaries locally or on a remote device.

Platform Support

In addition to the NVIGI SDK’s existing support for x64 devices, this release adds ARM64 platform support as an RTX Spark Developer Preview. However, building the SDK on an ARM64 device is not currently supported. ARM64 binaries must be cross-compiled on an x64 and so debugging must be done remotely on an x64 host machine connected to the target ARM64 device. There are additional requirements when building for and debugging ARM64 binaries and they will be covered in the following Prerequisites section.

Several scripts contained within the NVIGI SDK will have command line parameters that allow the user to specify which platform they wish to target. These scripts typically default to x64 support if no platform is specified, but you may pass either -x64 or -arm64 to explicitly choose the target platform.

The following placeholders are used in this document:

  • <SDK_ROOT>: the root of the SDK Plugins tree, which contains the bin directory for the SDK.

  • <SDK_PLATFORM>: the target CPU architecture. See Platform Support for information on supported platforms; replace with either x64 or arm64.

Also note that the NVIGI SDK can be used on an ARM64 device in x64 emulation mode. In that case, use x64 as the target platform and build on an x64 machine as normal. The resulting x64 binaries run on the ARM64 device via Windows emulation. Remote debugging is still required: the x64 machine acts as the debugging host and connects to msvsmon.exe running on the ARM64 device, exactly as described in the remote debugging section of this document — the only difference is that the x64 build and x64 project settings are used rather than ARM64.

IMPORTANT: The NVIGI 1.7.0 RTX Spark Developer Preview:

  • Does NOT support building for the ARM64 target the core libraries or the plugins themselves from the full source posted to GitHub.

  • DOES still support building the entire SDK (inc. core and plugins) x64 target from GitHub source

  • DOES support building the samples provided with the binary releases from the source in the release packs for either platform.

  • An upcoming full release for RTX Spark will add support for building the entire SDK including core libraries and the plugins themselves for ARM64 target from source.

IMPORTANT: The RTX Spark Developer Preview does not support CiG - the 3D Samples currently disable CiG on Spark, and application developers should not enable CiG in their applications on Spark. Updates to the Spark driver and NVIGI SDK will be released later to enable CiG. Enabling CiG on the initial release may lead to application crashes.

Prerequisites

NVIGI version 1.7.0

Minimum

Recommended

GPU

RTX 30x0/A600

RTX 4080/4090 or RTX 5080/5090

VRAM

8GB

12GB

Windows

Win11 22H2 (version 22H2 - 10.0.22621)

Graphics Driver

r555.85

Development Tools

VS Code or VS2022 with SDK 10.0.22621+

NOTE: Some plugins only support RTX 40x0 and above, and will not be available on RTX 30x0.

For ARM64 cross-compilation, the following additional requirements apply:

Requirement

Details

Visual Studio 2022

Must include the MSVC ARM64 build tools component. In the VS Installer, enable Individual components → MSVC v143 - VS 2022 C++ ARM64 build tools.

ARM64 target device

A Windows on ARM device reachable over the network.

Visual Studio Remote Tools

The ARM64 version of Remote Tools for Visual Studio 2022 installed on the target device (needed for remote debugging).

Building

Setting Up the Build Environment

IMPORTANT: As detailed in Plugins, there must be either:

  • An instance of the NVIGI Core SDK located at <SDK_ROOT>/nvigi_core, or

  • A directory junction link from <SDK_ROOT>/nvigi_core to a built and packaged copy of the NVIGI Core PDK.

Open a Visual Studio Developer Command Prompt in the <SDK_ROOT> directory and run:

setup.bat [-x64|-arm64]

This causes two things to happen:

  1. packman pulls all build dependencies and creates links in the external directory.

  2. premake generates project files in _project\vs20XX.

NOTE: If setup.bat fails with an error from packman, re-run it — there are rare link-creation issues on the initial run.

NOTE: You cannot mix x64 and ARM64 in the same _project tree. To switch between architectures, re-run setup.bat with the appropriate flag (-x64 or -arm64), which regenerates the project files.

Building

To build, open _project\vs20XX\nvigi.sln in Visual Studio, ensure that the Platform dropdown displays the correct target platform, select the desired build configuration, and build.

NOTE: Minimal OS configuration is needed to build — the specific Windows version and NVIDIA driver are runtime dependencies, not compile/link-time dependencies. This allows the SDK to build on stock virtual machines with zero configuration.

After building, the built artifacts reside under _artifacts. Copy them to the expected locations by running:

copy_sdk_binaries.bat [-x64|-arm64] [Release|Debug|Production]

This copies the core library, DLLs, and executables into bin\<SDK_PLATFORM>\<configuration>. The three build configurations are:

  • Release: optimized build for local development and testing.

  • Debug: unoptimized build with full debug symbols for stepping through SDK code.

  • Production: optimized build intended for distribution; plugins are signed and debug output is suppressed.

Modifying Projects

IMPORTANT: Do not edit the MSVC project files directly. Always modify premake.lua or files in the premake directory.

When changing an existing project’s settings (e.g. adding a source file, changing a compiler setting, or linking a new library), re-run setup.bat after making changes, then reload the solution in the IDE.

NOTE: NVIDIA does not recommend making changes to the headers in include, as these affect the API itself and can make developer-built components incompatible with NVIDIA-supplied components.

Deploy to the Remote Device

NOTE: This step is required whenever you intend to run or debug on a remote device. Skip it if you are running and debugging locally on the build machine.

To remotely debug a locally build SDK, deploy the staged directory to the remote device. Transfer bin\<SDK_PLATFORM>\<configuration>\ and the data\ tree using any mechanism — network share, robocopy, USB, etc.

Example using robocopy to deploy ARM64 binaries to an ARM 64 device:

robocopy bin\arm64\Release \\<device-name>\share\nvigi\bin\arm64\Release /MIR
robocopy data              \\<device-name>\share\nvigi\data              /MIR

Debug Build Dependencies

Running Debug builds of the samples requires the presence of several Debug DLLs that are shipped with versions of Visual Studio and the Windows SDK. If you already have a build environment installed on the target device, then these DLLs are likely already in place and will not require any additional configuration. If not, then they will need to be copied from a machine that has them to the remote device in the same directory as the executable to be run.

The DLLs required from Visual Studio reside in a sub-tree of the debug_nonredist folder within its installation location. The full path depends on the installed version of Visual Studio, its installation location, and the target platform, but the default location will be:

C:\Program Files\Microsoft Visual Studio\2022\Professional\VC\Redist\MSVC\<MSVC_VERSION>\debug_nonredist\<SDK_PLATFORM>\

In this folder, you will find several sub-folders. Do not copy the contents of the folder in their current layout, but rather copy each of the .dll files within each folder to the directory containing the executable to be run.

You will also need one DLL from the Windows SDK. Again, the location of this file will depend on the version of the Windows SDK that you are using, the SDK’s installation location and the target platform. The default location for this DLL is:

C:\Program Files (x86)\Microsoft SDKs\Windows Kits\10\ExtensionSDKs\Microsoft.UniversalCRT.Debug\<WINDOWS_SDK_VERSION>\Redist\Debug\<SDK_PLATFORM>

Ensure that you are using the correct versions of the DLLs for your platform. For Native ARM64 builds, use the ‘arm64’ sub-folders (as <SDK_PLATFORM>). For x64 builds, either on an x64 device or running under emulation on ARM64, use the ‘x64’ sub-folders (as <SDK_PLATFORM>).

Running On ARM64

On the ARM64 device, run the sample with the same command-line arguments as the x64 variants:

nvigi.basic.exe --models <path-to-models> --speaker <path-to-speaker-json>

Debugging

Local Debugging in Visual Studio

All NVIGI samples follow the same procedure for local debugging in Visual Studio 2022. Because built artifacts land in _artifacts but the samples must run from bin\<SDK_PLATFORM>\<Configuration> (where all DLLs and the executable coexist), the VS debugger must be directed to launch the staged copy of the executable.

One-Time Project Configuration

For each sample you want to debug, in Visual Studio open the project properties (right-click the project → Properties → Debugging) and set:

Property

Value

Command

<SDK_ROOT>\bin\<SDK_PLATFORM>\<configuration>\<sample>.exe

Command Arguments

Sample-specific (see individual sample documentation)

Working Directory

<SDK_ROOT>\bin\<SDK_PLATFORM>\<configuration>

NOTE: These settings are stored in the _project directory and must be re-applied if _project is deleted and setup.bat is re-run.

Per-Sample Debug Settings

Each sample may require specific VS project settings, executables, and command arguments. See the individual sample’s documentation for the debug settings specific to that sample.

After Each Build

After every build, re-run the binary staging script before launching the debugger:

copy_sdk_binaries.bat [-x64|-arm64] [Release|Debug|Production]

The Release configuration is recommended for debugging — it is optimized but retains debug symbols.

Remote Debugging

When debugging on the build machine is not an option, such as when cross-compiling for ARM64, Remote Debugging must be used and VS2022 on the x64 machine acts as the host debugger; msvsmon.exe on the remote device acts as the remote debugger agent.

One-Time Setup on the Remote Device

  1. Download Remote Tools for Visual Studio 2022 for the appropriate platform from the Visual Studio downloads page and install them on the target device.

  2. Launch the Remote Debugger: Start Menu → Remote Debugger (or run msvsmon.exe directly).

  3. Note the connection string shown in the Remote Debugger window, e.g.:

    my-remote-device:4026

  4. Ensure the firewall on the remote device allows inbound connections on the port shown (default: 4026).

Configure Visual Studio on the Build (Host) Machine

  1. In VS2022, open _project\vs2022\nvigi.sln.

  2. Set the active platform to the target platform and the configuration to Release (or Debug).

  3. Right-click the sample project → Properties → Debugging.

  4. Set the following properties:

Property

Value

Debugger to launch

Remote Windows Debugger

Remote Command

Full path (on the remote device) to the executable, e.g. <device-path>\bin\arm64\Release\nvigi.basic.exe

Command Arguments

Sample arguments using paths (on the remote device)

Working Directory

Path (on the remote device) tobin\<SDK_PLATFORM>\<configuration>

Remote Server Name

Themsvsmon.exe connection string, e.g. my-remote-device:4026

Connection

Remote with Windows Authentication (adjust if the device is not domain-joined)

Important: All paths entered here are resolved on the Remote Device, not the build machine.

  1. Click OK to save.

Starting a Remote Debug Session

  1. Ensure the latest Target binaries are deployed to the remote device (re-run the staging and deploy steps after every build).

  2. Verify msvsmon.exe is running on the remote device.

  3. In VS2022 on the build machine, press F5 (or Debug → Start Debugging).

VS2022 will connect to msvsmon.exe, upload symbol information, launch the executable on the remote device, and attach the debugger. Breakpoints, watch windows, call stacks, and all other VS2022 debugger features work normally.

Attaching to a Running Process

If the sample is already running on the remote device (e.g. to catch a startup race condition), use Debug → Attach to Process:

  1. Set Connection type to Remote with Windows Authentication (or Remote (no authentication) as appropriate).

  2. Set Connection target to the msvsmon.exe connection string.

  3. Click Find to list processes running on the device.

  4. Select the target process and click Attach.