diff --git a/.gitignore b/.gitignore index c81dc3343ed..e5620675e8b 100644 --- a/.gitignore +++ b/.gitignore @@ -59,3 +59,6 @@ _coverage/ # Jane Street Merlin support /.local-merlin-binaries /.local-ocaml-lib + +# Debugger support +ocamlc diff --git a/HACKING.md b/HACKING.md index 9b8c2c8d386..d2fca29268a 100644 --- a/HACKING.md +++ b/HACKING.md @@ -11,7 +11,9 @@ want to modify the Flambda backend. Jump to: - [Running tests](#running-tests) - [Running only part of the upstream testsuite](#running-only-part-of-the-upstream-testsuite) - [Running tests with coverage analysis](#running-tests-with-coverage-analysis) -- [Running the compiler produced by "make hacking" on an example without the stdlib](#running-the-compiler-produced-by-make-hacking-on-an-example-without-the-stdlib) +- [Running the compiler produced by "make hacking" on an example without the + stdlib](#running-the-compiler-produced-by-make-hacking-on-an-example-without-the-stdlib) +- [Using the ocaml debugger to debug the compiler](#using-the-ocaml-debugger-to-debug-the-compiler) - [Getting the compilation command for a stdlib file](#getting-the-compilation-command-for-a-stdlib-file) - [Bootstrapping the ocaml subtree](#bootstrapping-the-ocaml-subtree) - [Testing the compiler built locally with OPAM](#testing-the-compiler-built-locally-with-opam) @@ -202,6 +204,34 @@ something like: ./_build/_bootinstall/bin/ocamlopt.opt -nostdlib -nopervasives -c test.ml ``` +## Using the OCaml debugger to debug the compiler + +Run `make debug`. This completes three steps: + +1. `make install` +2. Sets up the `ocaml/tools/debug_printers` script so that you can `source + ocaml/tools/debug_printers` during a debugging session to see + otherwise-abstract variable values. +3. Symlinks `./ocamlc` to point to the bytecode compiler. This is convenient for + emacs integration, because emacs looks for sources starting in the directory + containing the executable. + +To actually run the debugger from emacs (other workflows are possible; just +tweak these instructions): + +1. Run `M-x camldebug RET` +2. Choose the `ocamlc` symlink in the root of the repo. +3. Choose the arguments to pass to `ocamlc`, likely a full path to a test `.ml` + file. +4. Choose the built `ocamldebug`, in your install directory. +5. Set any breakpoints you want. The easiest way is to navigate to the line + where you want the breakpoint and use `C-x C-a C-b` in emacs. +6. Install the debug printers, with `source ocaml/tools/debug_printers`. +7. `run` to your breakpoint. + +See [the manual section](https://v2.ocaml.org/manual/debugger.html) for more +information about the debugger. + ## Getting the compilation command for a stdlib file For example because you need to get the `-dflambda` output because of a bug. @@ -387,4 +417,4 @@ only runs on Linux, although it shouldn't be hard to port to macOS, especially if using GNU binutils. It is recommended to install the Jane Street `patdiff` executable before running `make compare`. The comparison script has not been maintained since the early releases of the Flambda backend; it was written as part of the acceptance process -for the initial release. + for the initial release. diff --git a/Makefile b/Makefile index e19cc782b44..0d800b30f64 100644 --- a/Makefile +++ b/Makefile @@ -160,3 +160,17 @@ coverage: boot-runtest --source-path=. \ --source-path=_build/default @echo Coverage report generated in _coverage/index.html + +.PHONY: debug +.NOTPARALLEL: debug +debug: install ocaml/tools/debug_printers ocamlc + +ocamlc: + ln -s $(prefix)/bin/ocamlc.byte ocamlc + +ocaml/tools/debug_printers: ocaml/tools/debug_printers.ml ocaml/tools/debug_printers.cmo + echo 'load_printer "ocaml/tools/debug_printers.cmo"' > $@ + awk '{ print "install_printer Debug_printers." $$2 }' < $< >> $@ + +ocaml/tools/debug_printers.cmo: ocaml/tools/debug_printers.ml _build/install/main/bin/ocamlc.byte + _build/install/main/bin/ocamlc.byte -c -I _build/main/ocaml/.ocamlcommon.objs/byte ocaml/tools/debug_printers.ml diff --git a/ocaml/tools/dune b/ocaml/tools/dune index 90c5f965daf..737ed27a95e 100644 --- a/ocaml/tools/dune +++ b/ocaml/tools/dune @@ -91,16 +91,4 @@ (libraries ocamlcommon) (modules debug_printers)) -(rule - (target debug_printers) - (deps debug_printers.ml %{cmo:debug_printers}) - (action - (with-stdout-to %{target} - (progn - ; Resorting to Bash instead of the built-in [echo] action because I - ; couldn't find a better way to get an absolute path out of Dune - (bash "echo load_printer \\\"$(realpath %{cmo:debug_printers})\\\"") - (with-stdin-from debug_printers.ml - (run awk "{ print \"install_printer Debug_printers.\" $2 }")))))) - ; ocamlcp, ocamloptp and ocamlprof are not currently supported.