Skip to content

IDE Integrations: C++ & Debugging

There are many available extensions but the most useful are the extensions that teach VSCode about C++ and enable code completions and documentation accessibility via IntelliSense. You have two main options, but can only use one of these at a time.

  • LLVM clangd (llvm-vs-code-extensions.vscode-clangd) is the best option for IntelliSense auto-completion. Most users will want this.
  • The C++ extensions from Microsoft (ms-vscode.cpptools) can also be used but performs worse for IntelliSense (usually giving false errors, not being able to fully load the athena source tree, etc.). However it can be more useful for debugging (see below).

Athena Integrations

The following files/symbolic links are available in the build directory

  • compile_commands.json: a file containing full compile commands list
  • ide_compiler: a symbolic link to the compiler executable used by Athena
  • ide_gdb_runner: an executable gdb runner script that supports also running in a container (see below)
  • ide_gdb_wrapper: an executable gdb wrapper using Athena build environment

GDB runner is designed in a way that it can run on any machine. The compiler may also run on newer versions of the OS than it was built for.

VS Code C++ Setup

The Athena repository provide a default c_cpp_properties.json configuration file

{
    "configurations": [
        {
            "name": "Linux",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": [],
            "compilerPath": "${workspaceFolder}/../build/ide_compiler",
            "cStandard": "c11",
            "cppStandard": "c++20",
            "intelliSenseMode": "gcc-x64",
            "compileCommands": "${workspaceFolder}/../build/compile_commands.json"
        }
    ],
    "version": 4
}

No extra action is needed from your side to use the integrations as long as your build directory is at the same level as the source directory and named build.

This enables code completion and navigation features in VS Code. Also all compilation errors are highlighted in the editor. Note that compilation warnings are not shown by the default extension yet. To detect them at the compilation stage, you can export CXXFLAGS before executing CMake

export CXXFLAGS="-Werror"

Supported Workflows

Code autocompletion and validation

VS Code will validate the C++ code and show potential issues and warnings.

VS Code C++ Error

Tips

As Athena repository is quite large the LLVM clangd extension usually handles it better than the default Microsoft one.

Formatting

A default clang-format configuration file is also available in the repository (.clang-format). If you want to format C++, please use this configuration file instead of your own.

Debugging

Alert

The Microsoft C++ extension is currently required for this as the LLDB extension is not mature enough yet.

First you need to make a run configuration for the task you want to debug by going to the Run and Debug tab in the sidebar and clicking create a launch.json file. In the configurations array, add a new object with the following fields:

{
  "name": "(gdb) OverlayTest",
  "type": "cppdbg",
  "request": "launch",
  "cwd": "${workspaceFolder}/../run",
  "program": "${workspaceFolder}/../build/ide_python",
  "args": [
    "${workspaceFolder}/../build/x86_64-el9-gcc14-opt/share/OverlayTest.py",
    "-t", "1", "-n", "5", "Truth"
  ],
  "MIMode": "gdb",
  "miDebuggerPath": "${workspaceFolder}/../build/ide_gdb_runner"
}

Usually what you need to change is the name and args fields, if you do not want to run via python configuration but some C++ executable directly.

Breakpoints can be set directly in the code by clicking left to the line number. Once the code stops at the breakpoint the line will get highlighted. VS Code Python Breakpoint

Then you can start debugging by pressing F5 or using the Run > Start Debugging menu.

Once the breakpoint is reached or the code crashes, stack trace is also available. VS Code Python Stack Trace

Debugging in a container and Advanced options

If you need to call custom asetup command other than asetup --restore, you can provide it in the ATLAS_IDE_ASETUP_CALL. Multiple calls can be done, separated by semicolon ;.

There are two options to run in a container:

  1. SSH directly into the container (see more details on SSH connections).
  2. Run GDB in a container.

To run GDB in a container set ATLAS_SINGULARITY_IMAGE when running CMake to enable debugging in a container. It supports any container engine supported by Apptainer/Singularity. ATLAS_SINGULARITY_ARGS can be used to mount needed paths if not mounted by default. For example:

cmake -G Ninja \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=TRUE \
  -DATLAS_ENABLE_IDE_HELPERS=TRUE \
  -DATLAS_IDE_ASETUP_CALL="asetup none,gcc13,cmakesetup" \
  -DATLAS_SINGULARITY_IMAGE="/nfs/dust/atlas/user/tadej/singularity/alma9-dev.sif" \
  -DATLAS_SINGULARITY_ARGS="--contain --bind /afs:/afs --bind /cvmfs:/cvmfs --bind /data:/data --bind /nfs:/nfs --bind /pnfs:/pnfs --bind /var/tmp:/var/tmp --bind /var/data:/var/data --bind /tmp:/tmp" \
  /var/data/tadej/development/full/athena/Projects/Athena