How can I run a debugger against the codebase?

[ahelwer]

I've been trying to do this a few different ways without much success. I would like to (in increasing order of complexity):

1. Run the OCaml CLI debugger against the full TLAPM executable
2. Run the OCaml CLI debugger on a single unit test
3. Run the OCaml debugger through VS Code

I am happy to encode the instructions for doing this in the development documentation upon learning them.

[ahelwer]

Running ocamldebug on the full TLAPM executable

1. Ensure -g flag is passed to OCaml compiler & linker
   • Dune does this by default; see dune printenv . output
2. Add (modes byte) to dune (executable) stanza to output bytecode (.bc) file
   • See PR Emit bytecode in dune build for debugging #144
   • Outputs to _build/default/src/tlapm.bc and src/tlapm.bc
3. Run CAML_LD_LIBRARY_PATH=_build/default/src:$CAML_LD_LIBRARY_PATH
   • This tells the debugger where to pick up the native dlltlapm_lib_stubs.so file
4. Run ocamldebug src/tlapm.bc
   • To get GNU Readline editing niceties, prefix this with rlwrap
5. Set a breakpoint at tlapm_lib.init with break @Tlapm_lib 552
6. Run run to advance to the breakpoint

Running ocamldebug against a unit test

This does not seem possible against inline unit tests; see:

• https://stackoverflow.com/q/78750976/2852699
• Is it possible to run an inline test in ocamldebug? janestreet/ppx_inline_test#48

For regular unit tests (that live as separate files in the test dir) this can be done as follows:

1. Create a new directory under the test dir for your unit tests, for example mytest
2. Create a test file (for example) at test/mytest/testname.ml and write your tests inside it
3. Create a dune build file at test/mytest/dune with the following contents (testname must match your test file name):

(test
 (name testname)
 (modes byte exe)
 (libraries tlapm_lib)
)

4. Try running this test with dune runtest test/mytest --force --always-show-command-line
   • Note that with both modes defined the test will be run twice, unfortunately
   • Dune doesn't re-run tests if none of the inputs have changed unless you add --force
5. Run ocamldebug _build/default/test/mytest/testname.bc, or wherever it is dune executed the bytecode file

Running a debugger inside VS Code

1. Install the vscode-ocaml-platform extension in VS Code
2. Use OPAM to install the earlybird debug protocol adapter for OCaml
3. Run VS Code with the OCaml environment variables set appropriately, like after running opam env
   • This ensures the debugger can find the OCaml standard library and various dependencies
4. Ensure Dune outputs a bytecode file (see above)
5. Ensure (map_workspace_root false) is set in the dune-project file
   • This ensures you can set breakpoints in the VS Code UI (they will show up as unverified otherwise)
   • See https://dune.readthedocs.io/en/stable/reference/dune-project/map_workspace_root.html
6. Create the following file at .vscode/launch.json in the repo root:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "TLAPM Debug",
            "type": "ocaml.earlybird",
            "request": "launch",
            "program": "${workspaceFolder}/src/tlapm.bc",
            "stopOnEntry": true,
            "env": {
                "CAML_LD_LIBRARY_PATH": "${workspaceFolder}/_build/default/src:${env:CAML_LD_LIBRARY_PATH}"
            }
        }
    ]
}

13. Create a breakpoint somewhere in the program then run the configuration from the VS Code debug menu

[ahelwer]

Unfortunately after a lot of experimentation I've found that debugging in ocaml is simply too immature to rely on for development. It is very finicky to set up and will often fail to find events or source code when setting breakpoints. So despite all the work to figure this out I am not using it. A good alternative is to use the utop REPL, which you can activate by running opam install utop then dune utop to open a REPL with all the TLAPM libraries available.