How to use the GDB debugger with OpenMolcas?

Question

I would like to follow how some variables are changing during an OpenMolcas calculation, and adding WRITE statements has become too tedious. I've compiled with the -DCMAKE_BUILD_TYPE=Debug option:

cmake ../OpenMolcas_HPQC_LEVEL -DCMAKE_BUILD_TYPE=Debug
make -j8

I've set the PATH accordingly:

pymolcas
> MOLCAS has been found at /home/nike/build_OpenMolcas_HPQC_LEVEL_Debug

Attempts to use gdb have failed, for example:

gdb --args pymolcas
> "/home/nike/build_OpenMolcas_HPQC_LEVEL_Debug/pymolcas": not in executable format: file format not recognized

When searching the word "debug" on the Molcas forum I got about 29 results, but most of them were about running calculations in parallel (I am not), or just had the word debug in the post because it was part of the CMAKE output, even if the post had nothing to do with debugging. The most relevant results that I found there were:

• The -D DEBUG_DEFS=_DEVEL_ was recommended here but that was in the context of turning errors into warnings (which is not what I'm trying to do).
• This post) includes an output file that says "To debug your program, run it with the --sync command line option", but it's in the context of LUSCUS and pymolcas -h suggests that --sync isn't an option for pymolcas.

I also searched the documentation, and found that there's a MOLCAS_DEBUGGER environment variable but running export MOLCAS_DEBUGGER=gdb before the above gdb command leads to the same error (and I assume this environment variable affects the running of molcas rather than pymolcas). The word "debug" shows up a few times in the Documentation PDF (18 times to be exact) but mainly in the context of printing more output, in addition to the afformentioned CMAKE build type and the MOLCAS_DEBUGGER variable

The word debug appears another 71 times in the CMakeLists file but rather than going through every possibility there, if there's perhaps a set of instructions on how to use gdb with OpenMolcas (perhaps in the documentation), it would be helpful if you could let me know them!

Answer 1

pymolcas runs each program as a separate process, so you need to insert gdb before each individual program call, and not before pymolcas. This is what MOLCAS_DEBUGGER is supposed to achieve. Try:

MOLCAS_DEBUGGER=gdb pymolcas ...

PS: For OpenMolcas-specific questions you can use https://openmolcas.zulipchat.com/

Answer 2

The following eventually worked for me, especially after Jellby's most recent comment:

Compiling:

cmake ../OpenMolcas_HPQC_LEVEL -DCMAKE_BUILD_TYPE=Debug
make -j8
export PATH=$PATH:/home/nike/build_OpenMolcas_HPQC_LEVEL

Debugging:

MOLCAS_DEBUGGER=gdb pymolcas inputFile.input

Unlike some programs, in which you might run something like gdb --args ~/path/to/program/level.exe followed by run < inputFile.input to have level.exe run with the input file inputFile.input, the run command is not used at this stage because the above command involving MOLCAS_DEBUGGER will invoke Molcas to start running immediately with the input file inputFileinput. After parsing the input file it will start running gdb before running the "module" or "program" within Molcas that your input file wishes to invoke. In my case the first line of the input file was &LEVEL so after parsing and printing (in the command window) the input file, it printed:

--- Start Module: level at Tue Dec 13 07:19:04 2022 ---
GNU gdb (Gentoo 9.1 vanilla) 9.1
Copyright (C) 2020 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Type "show copying" and "show warranty" for details.
This GDB was configured as "x86_64-pc-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<https://bugs.gentoo.org/>.
Find the GDB manual and other documentation resources online at:
    <http://www.gnu.org/software/gdb/documentation/>.

For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from /home/nike/build_OpenMolcas_HPQC_LEVEL_Debug/bin/level.exe...
(gdb)

At the gdb prompt I was able to set my breakpoint and to run the "module" or "program":

(gdb) b level.f:10
(gdb) r

This was the output:

Starting program: /home/nike/build_OpenMolcas_HPQC_LEVEL_Debug/bin/level.exe 
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/cvmfs/soft.computecanada.ca/gentoo/2020/lib64/libthread_db.so.1".

()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()

                                               &LEVEL

                                   only a single process is used
                       available to each process: 2.0 GB of memory, 1 thread?
                                             pid: 34832
()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()()


Breakpoint 1, level (rc=7844255429672472576) at /home/nike/OpenMolcas_HPQC_LEVEL/src/level/level.f:76
76        NLEV2= -1
(gdb) 

which is exactly what I was hoping to achieve 🙂

Summary:

Compile with the above commands, then debug/run with MOLCAS_DEBUGGER=gdb pymolcas inputFile.input and you should then be able to use gdb in the way that you're familiar.