togglelog - an OCaml PPX extension for zero-cost debug logging
This was an experiment and my first PPX driver. Further development is currently unlikely.
This is a PPX extension for OCaml that allows you to add logging to your code which is completely removed at compile time in release builds. It also provides some primitive filtering ability when logging is compiled into the programs.
let () = [%toggle_log "Hello, world!"]; [%toggle_log "SPECIFIER" (some_potentially_expensive_function ())]
By default, the above code will be translated to (something equivalent to) the following:
let () = (); ()
The PPX rewriter has an
--enable flag which can be used to enable logging. When enabled, the above code will be translated to (approximately) the following:
let () = Printf.printf "[LOG - example.ml:1:9] %s\n" "Hello, world!"; Printf.printf "[LOG (SPECIFIER) - %s\n" (some_potentially_expensive_function ())
You can see the exact code generated in the tests.
This lets you add logging to your code without worrying about the performance impact in release builds.
togglelog in your Dune project, add the following to your
(exectuable (name myexe) (preprocess (pps togglelog)) (instrumentation (backend togglelog --enable)))
This sets up
togglelog to be used during all builds, but will only enable logging when Dune is invoked with the
--instrument-with togglelog flag.
When two arguments are passed to the
%toggle_log PPX, the first is a "specifier". This literal string is printed as part of the message, but can also be used to filter the output of the logger.
By default, all log messages are printed. However, if the
OCAML_TOGGLELOG environment variable is set to a comma-separated list of specifiers, only messages with matching specifiers will be printed.