From all of the available VS Code extensions you should install at the very least
The following files/symbolic links are available in the build directory
compile_commands.json
: a file containing full compile commands listide_compiler
: a symbolic link to the compiler executable used by Athenaide_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 environmentGDB 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.
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"
VS Code will validate the C++ code and show potential issues and warnings.
As Athena repository is quite large the LLVM
clangd
extension usually handles it better than the default Microsoft one.
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.
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-gcc13-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.
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.
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:
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