OpenFOAM Debug Mode

Here are some instructions on how to enable debugging in OpenFOAM for those using Windows Subsystem for Linux (WSL), mostly based on this article and this article by Mustafa Abbas on his Medium page. He has, however, made a couple of omissions / mistakes in his articles, so I have added some corrections here.

This page is a work-in-progress by Nik Lebedenko. Please let me know if you run into any issues at all (even if they're easily solved; it will help others avoid common pitfalls).

Installing Visual Studio Code with Ubuntu support

• Make sure you have Visual Studio Code (not Visual Studio) installed on your Windows system.
• Open Visual Studio Code, and click on the Extensions tab (CTRL+SHIFT+X) on the left side of the screen.
• Download these two extensions by pasting their IDs into the search bar, pressing Enter, and clicking "Install":
  • ms-vscode.cpptools
  • ms-vscode-remote.remote-wsl
• You should now be able to run code . in a Ubuntu terminal, and it should open Visual Studio Code in the same directory you ran the command in.

Compiling OpenFOAM in debug mode

• This step will take a while to run, perhaps an hour or two.
• Edit $FOAM_ETC/bashrc with your preferred text editor (use nano if in doubt) and change the line with WM_COMPILE_OPTION=Opt to WM_COMPILE_OPTION=Debug
• Save and close the file, and restart Ubuntu, then run the following commands:

  cd $WM_PROJECT_DIR
  sudo chown -R $USER .
  ./Allwmake -j -s -q -l    ### this will take time!
  sudo apt install gdb

Setting up the Visual Studio Code files for OpenFOAM

• Copy the source code for simpleFoam into your personal OpenFOAM simulation folder (e.g. ~/OpenFOAM-sims) and open it by running these commands:

  cp -r $FOAM_SOLVERS/incompressible/simpleFoam ~/OpenFOAM-sims
  code ~/OpenFOAM-sims/simpleFoam

• Download this Github repository, and copy the c_cpp_properties.json, launch.json, and tasks.json, files from the vscode folder you downloaded, into your .vscode folder
• You should now be able to click on the "Run and Debug" tab on the left side of the screen, selecting "OF-debug" from the drop-down in the top-left.
• Open the simpleFoam.C file by navigating back to the "Explorer" tab and clicking on the simpleFoam.C file in the tree.
• Add a breakpoint somewhere in the code by left-clicking to the left of the line number you want the breakpoint at - for example, at the line with argList::addNote. See this blog post if unsure.
• Start debugging by pressing F5.
• After a short while of compiling, the code should run until it hits the breakpoint you set. You can now step through the code, line by line, and see exactly what OpenFOAM is doing under the hood.

Going back to optimised mode

This is as simple as editing $FOAM_ETC/bashrc again, setting WM_COMPILE_OPTION=Opt, and restarting Ubuntu (or re-sourcing that file). OpenFOAM has separate folders to store the binary files for debug and optimised modes, making it easy to switch between them without having to recompile.