Debugging problems

Breakpoints not working

Symptom: Debugger does not stop on breakpoints / breakpoints are grayed-out.

This usually means that the debugger cannot locate debugging symbols for your program. Here are a few things to check:

• Check whether you are compiling with debug symbols. Most C++ compilers, as well as the Rust compiler, use -g flag to enable emission of debug info. When using a build system, such as CMake or Cargo, make sure you've selected a debug build type. You can check whether your binary has debug symbols by following these instructions.

• If debugging a Rust program, check whether the location of your source files contains symlinks: rustc normalizes source paths embedded in debug info, so the debugger will search for them at non-symlinked location. To fix this you can add "sourceMap": {"<original path>: "<symlinked path>"} to launch conflagration.

• Try to break inside your code and examine source file path that got embedded in debug info:

  • In VSCode Breakpoints view click on '+', then type the name of some function that gets called early on in your code. If you can't think of anything else, "main" will do.
  • Start debugging. Once execution breaks, you should see a disassembly view of the main function.
  • Look for 'Source location:' in the header. This will tell you where the debugger thinks the source file is located. Chances are, that path is be incorrect, but you'll be able to fix it using sourceMap.
  • Beware that there may be more than one 'main' function. For example, Rust programs typically have two: the runtime entry point and the actual program entry point. If you saw 'Source location: unknown' in previous step, you have probably stopped at the first one.

Debugging Swift

Symptom: When debugging Swift binaries, local variables are garbled or not shown at all.

The default LLDB backend bundled with CodeLLDB supports C, C++, Rust, as well as many other languages whose debug info is compatible with C++, however this list does not include Swift. It appears that Swift has diverged far enough from C++ that LLDB cannot interpret its debug info without a special Swift plugin.
It is, however, still possible to debug Swift programs using CodeLLDB by directing it to use an alternate debugger backend, namely, the one provided with the Swift toolchain:

• Open VSCode commands palette and search for "LLDB: Use Alternate Backend..." command.
• At the prompt, enter executable name of the LLDB instance you want to use. On MacOS, you should use the default system instance (i.e. just lldb). On Linux, look for lldb in <swift install root>/usr/bin directory.
• If all goes well, CodeLLDB should report that it has located the library it needs and ask for your confirmation, after which it will add lldb.library configuration setting in the current workspace. If auto-detection does not work, you can also locate liblldb...so/dylib/dll manually.

Debugging Electron app plugins

Symptom: Electron applications fail to launch under the debugger with an error similar to this:

const rc = app.rc = require('../rc')      
TypeError: Cannot set property 'rc' of undefined

Electron applications typically consist of several cooperating processes, some of which have specific roles, as configured by environment variables set the main process. Since VSCode is an Electron application itself, its children, including the debugger and the debuggee will inherit these variables as well, which may cause them to function incorrectly. The solution is to reset all ELECTRON_... variables in the launch configuration:

"env": { 
    "ELECTRON_RUN_AS_NODE": "",
    "ELECTRON_NO_ATTACH_CONSOLE": "",
}