Note

The undo debug type is experimental. It is not yet the default debug type for the Time Travel Debug for C/C++ extension, but we encourage you to try it and let us know what you think by contacting Undo Support

Migrating to the `undo` debug type¶

Undo’s Time Travel Debug for C/C++ extension supports two debug types: cppdbg (the original integration, which uses the Microsoft C/C++ extension as an intermediary) and undo (a newer integration that communicates with UDB directly over the Debug Adapter Protocol).

The undo debug type supports both launch and attach configurations, and offers several advantages over cppdbg:

All commands are interruptable with the Pause button in the debug toolbar.
Breakpoints set in the UDB command-line terminal appear in the VS Code breakpoints pane.
Improved error messaging on debugging session startup.
Improved handling of edge cases, including correct behavior at the start and end of recorded history.
Improved performance.

The undo debug type requires UDB version 10.0 or later, and Time Travel Debug for C/C++ version 3.0.0 or later.

Added in version 10.0.

Automatic migration of existing configurations¶

Time Travel Debug for C/C++ version 3.0.0 provides a command to automate the migration to the undo debug type. After ensuring your setup satisfies the requirements above, you can do the following to convert all your existing cppdbg UDB configurations (from your workspace launch.json file) to use the new undo debug type.

Open the command palette (Ctrl+Shift+P).
Run Undo: Migrate legacy UDB “cppdbg” launch configurations to use the experimental “undo” debug type.

The command appends a new undo configuration to your launch.json for each existing cppdbg configuration that has a udb property. The original cppdbg configurations are marked as legacy with (legacy) to distinguish them from the newly created undo configurations.

The command performs all the property conversions described below, with one exception: for setupCommands entries, only debugger commands with an -exec prefix, or -enable-pretty-printing are automatically converted. Other MI commands are left unchanged and must be manually converted to their UDB equivalents.

Manual conversion of a launch or attach configuration¶

To manually convert your launch configuration to use the undo debug type, change your launch.json configuration as follows.

  {
      "name": "(UDB) Launch",
-     "type": "cppdbg",
+     "type": "undo",
      "request": "launch",
      "program": "${workspaceFolder}/a.out",
      "args": [],
      "stopAtEntry": true,
      "cwd": "${workspaceFolder}",
      "environment": [],
-     "MIMode": "gdb",
-     "miDebuggerPath": "/path/to/udb",
-     "miDebuggerArgs": "--keyfile /path/to/key",
-     "udb": "live",
+     "debuggerPath": "/path/to/udb",
+     "debuggerArgs": ["--keyfile", "/path/to/key"],
+     "mode": "live",
      "setupCommands": [
          {
-             "text": "-enable-pretty-printing",
+             "text": "set print pretty on",
              "ignoreFailures": true
          },
          {
-             "text": "-exec set pagination off",
+             "text": "set pagination off",
              "ignoreFailures": true
          }
      ]
  }

The key differences are:

"type" changes from "cppdbg" to "undo".
"udb" is replaced by "mode".
"miDebuggerPath" is replaced by "debuggerPath". If udb is on your PATH, this property can be omitted.
"miDebuggerArgs" (a string) is replaced by "debuggerArgs" (an array of strings, one element per argument or value).
"setupCommands" entries must be valid UDB commands rather than MI commands. For example, -enable-pretty-printing (an MI command) becomes set print pretty on.
"MIMode", "externalConsole", and "logging" are not used by the undo debug type and should be removed.

Limitations¶

Instruction-level reverse stepping is not supported from the debug toolbar. Reverse step commands are always executed at source-line granularity, regardless of whether the Disassembly view is active. The debug terminal can be used to issue reverse-stepi or reverse-nexti commands if required.

Progress for long-running commands is not displayed in the integrated terminal. Instead, an indicator will appear in VS Code while a long-running command is executing.

In the integrated terminal, subcommands are not autocompleted. For example, ugo time, ugo bookmark, etc. are not returned when tab-autocompleting ugo.

Property reference¶

For the full list of configuration properties supported by both the cppdbg and undo debug types, see the property reference in the extension’s README on the Visual Studio Code Marketplace.

Migrating to the undo debug type¶