IDE Integrations: C++ & Debugging

Last update: 20 Oct 2023 [History] [Edit]

Available 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.


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.

VS Code Example

The Athena repository provide a default c_cpp_properties.json configuration file

    "configurations": [
            "name": "Linux",
            "includePath": [
            "defines": [],
            "compilerPath": "${workspaceFolder}/../build/ide_compiler",
            "cStandard": "c11",
            "cppStandard": "c++17",
            "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"


First you need to make a run configuration for the task you want to debug using Run > Add Configuration… in the menu. 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": [
    "-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.

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.

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 \
  -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" \