[TOC]

7. Debugging LaMEM

If you are only a user of LaMEM, any text-editor is sufficient to change the *.dat LaMEM input files. Yet, if you are planning to do some more serious code development, it is quite helpful to install a more professional debugging environment such as Microsoft Visual Studio Code or Eclipse.

7.1. Microsoft Visual Studio Code

Microsoft Visual Studio Code is a recent and open-source development by Microsoft which has quickly become the number one development environment among professional programmers. It runs on Linux, Mac and Windows and provides a very simple way to get debugging to work with PETSc. It also allows you to do development on a remote system almost as if it is on your local machine, which is pretty cool.

Here it will be assumed that we debug on Mac OS, MPICH is installed via Homebrew, and PETSc and LaMEM are installed in the following folders

$ /Users/user/software/petsc/petsc-3.22.5-deb 
$ /Users/user/prog/LaMEM

which you obviously have to update for your system.

If you want to do remote debugging on a linux machine, you should first install the Remote SSH plugin and login to the remote server (this obviously requires you to have ssh login data to that machine). On the remote machine go to the /LaMEM/src directory.

The first thing to do is to add a file called c_cpp_properties.json inside the (hidden) directory /Users/user/prog/LaMEM/.vscode/ with the following content:

{
    "configurations": [
        {
            "name": "MacBook arm64",
            "includePath": [
                "${workspaceFolder}/**",
                "/opt/homebrew/include",
                "/Users/user/software/petsc/petsc-3.22.5-deb/include/"
            ]
        }
    ],
    "version": 4
}

This will tell the code where PETSc, and will give you info about all the PETSc routines within LaMEM if you hover over a PETSc command such as CHKERRQ with your cursor.

If you want to debugging as well, you need to make sure that you have a working debugger installed (for example the GNU debugger gdb, or on the newer arm64 apple systems the lldb debugger). On an arm64 apple system you would need to install the C/C++ extension as well as the CodeLLDB extension.

Once that is the case, you need to create a file called launch.json in the same hidden directory /Users/user/prog/LaMEM/.vscode/:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "(lldb) Launch",
            "type": "lldb",
            "request": "launch",
            "program": "/Users/user/prog/LaMEM/bin/deb/LaMEM",
            "args": ["-ParamFile","FallingBlock_IterativeSolver.dat","-nstep_max","2"],
            "stopOnEntry": false,
            "cwd": "/Users/user/prog/LaMEM/examples/BuiltInSetups/",
            "env": {"PETSC_DEB": "/Users/user/software/petsc/petsc-3.22.5-deb",
                    "PATH": "/opt/homebrew/bin:${env:PATH}"},
            "preLaunchTask": "C/C++: build LaMEM deb file",
        },   
    ]
}

For this to work, we also need to create a task that runs make mode=deb all in /LaMEM/src before we start the debugger, to rebuild the code. For this, you need to create a file tasks.json in /Users/user/prog/LaMEM/.vscode/:

{
    "tasks": [
        {
            "type": "cppbuild",
            "label": "C/C++: build LaMEM deb file",
            "command": "make",
            "args": [
                "mode=deb","all"
            ],
            "options": {
                "cwd": "/Users/user/prog/LaMEM/src",
                "env": {"PETSC_DEB":  "/Users/user/software/petsc/petsc-3.22.5-deb",
                        "PATH": "/opt/homebrew/bin:${env:PATH}"}
            },
            "problemMatcher": [
                "$gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "detail": "Task generated by Debugger."
        },
    ],
    "version": "2.0.0"
}

After this, you should be able to run LaMEM with the debugger, and even step inside PETSc routines.

7.2. Eclipse

The Eclipse Integrated Developer Environment is more difficult to set up. If you want more information about it, please have a look at LaMEM/info/installation/linux. Please note that Eclipse debugging is currently only functional on Linux platform since gdb debugger is no longer available on Mac OS, and native lldb debugger has very incomplete and fragile integration with Eclipse. Please consider using VS Code on Mac OS.