https://github.com/wardbrian/togglelog
A PPX writer which lets you compile out logging statements in release builds
https://github.com/wardbrian/togglelog
Last synced: about 2 months ago
JSON representation
A PPX writer which lets you compile out logging statements in release builds
- Host: GitHub
- URL: https://github.com/wardbrian/togglelog
- Owner: WardBrian
- License: mit
- Created: 2023-03-30T18:18:29.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-28T18:59:50.000Z (over 1 year ago)
- Last Synced: 2025-04-12T18:13:32.149Z (about 2 months ago)
- Language: OCaml
- Size: 24.4 KB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://ocaml.org/docs/metaprogramming) 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.
## Example
```ocaml
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:
```ocaml
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:
```ocaml
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](./test/output.t/run.t).
This lets you add logging to your code without worrying about the performance impact in release builds.
## Usage
### Dune
To use `togglelog` in your Dune project, add the following to your `dune` file:
```scheme
(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.
## Specifiers
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.