[ANN] Grace 💅, fancy diagnostics library for compilers

It is my pleasure to announce the initial release of Grace, a cutting-edge OCaml library :dromedary_camel: that includes a series of interfaces for building, reporting, and rendering beautiful compiler diagnostics.

To get started, simply run:

opam update
opam install grace

Key features

  • :triangular_ruler: Inline and multi-line error messages with associated priorities
  • :open_file_folder: Multi-file errors
  • :gear: Configurable rendering (styling and character set)
  • :rainbow: Coloured messages for ANSI terminals
  • :muscle: 100% OCaml

The project is still in its early phase with many additional features planned:

  • :books: Unicode support
  • :zap: LSP integration with linol
  • :eyes: Accessibility features such improved colour options and narratable renderers

I invite the community to play with Grace, exploring its capabilities and limitations. Your insights will play a crucial role in shaping the future of this library :slight_smile:


Is there a short comparison with asai somewhere?

Looks amazing!

Are there any plans to integrate this into the OCaml compiler itself?

Using this in the compiler: we discussed this briefly in feature request: better errors · ocaml/ocaml · Discussion #11924 · GitHub and then More multi-location error messages · Issue #12633 · ocaml/ocaml · GitHub .

The short answer is that it is a non-trivial amount of work (in particular, making good use of the capabilities of the library probably requires domain-specific work to compute different information at the point each error is computed), no one is actively working on it, and there is some preliminary work by @Octachron on error messages that would help or possibly be necessary.

The bulk of the compiler work on error messages comes from @Octachron and myself. One problem is that we tend to be too busy with release-management and PR reviews/triaging to free time to make good progress on this – there is always something more urgent that comes up, and it is hard to prioritize. We also have infrequent but nice contributions from other contributors (Julow, hhugo, smuenzel). It might be that we could make progress with some dedicated organization, just like we do for type-system changes, release management, triaging, etc.


Here is a brief comparison after quickly looking at the Asai docs:

  1. Both projects are diagnostic libraries, designed to assist in identifying and reporting issues within code.
  2. Both libraries roughly have the same types for diagnostics, however, Grace has a slightly richer API with labels and priorities, providing more control on what context is added.
  3. Renderers:
    • Asai has a simple ANSI renderer and a GitHub action renderer.
    • Grace, on the other hand, provides a complex ANSI renderer that supports Rust-style ASCII art error messages.
  4. Unicode support:
    • Asai handles unicode in sources, accommodating a broader range of characters in rendered errors
    • Grace doesn’t currently support unicode, but aims to handle unicode characters in future.
  5. Reporters/constructing diagnostics
    • Asai stands out by providing reporters for constructing diagnostics using algebraic effects.

Both libraries are rather opinionated, with Grace using JaneStreet’s core as a standard library replacement (although this will change in the future) and Asai extensively using algebraic effects.


Is it just me, or are ASCII art error messages a bit too distracting? I need error messages laid out in such a way that I can scan them quickly. Ideally, being parsimonious with extraneous wording, and taking advantage of indentation to show me the structure of an error. Seems I am against the current trend.


Thanks for the comparison! I had been looking at adding diagnostics to a tool I’m working on (https://discuss.ocaml.org/t/ocaml-is-awesome/13700). So Asai uses algebraic effects, which I can’t use because I’m stuck on OCaml 4 (and I need Windows). I tried installing Grace but as you mentioned it depends on core … the problematic dependency for me at the moment is core_unix which is not available on Windows.

I will take a look at Grace (not now though) to see how tightly coupled it is to core_unix.

Thanks for releasing the project!

Grace looks very cool, thanks for the release!

As an alternative for people wanting a more minimal solution, I released pp_loc a while ago, which basically extracts the message highlighting code from the ocaml compiler (>=4.08) as a separate library.


I also find it a bit distracting. I find that elm’s error messages strike the perfect balance and are easy to integrate into an editor like Vim.

It’s very easy to go overboard with colors and ascii art, and it tends to look very bad if you resize the terminal window.

With that in mind, our brain probably gets used to it quickly.

1 Like

Grace can absolutely be made more portable. core_unix was only used for Bigstring_unix which provides mmap’d big strings for opened files. I’ll open an issue for this :slight_smile:


I also occasionally find Rust’s error messages a bit too distracting. My goal for Grace isn’t only to permit a single style of error, but to have multiple configurable renders. The error format can then be configured by the user for their own preference / use cases.


I am happy to see that @Alistair made the initial release! As the main developer of asai, I can comment that both libraries separate the generation and rendering of diagnostics, so one can easily mix and match (modulo the small difference in our representations of diagnostics). We are implementing helper functions to make the combining of the two libraries trivial. The progress to use Grace to render diagnostics generated by asai is tracked by the GitHub issue 💅 Implement a handler based on grace · Issue #107 · RedPRL/asai · GitHub. We are interested in working with @Alistair to get the other direction done as well. :smiley:


We implemented the mmap trick directly in the asai codebase. We don’t want to include the mmap code in our library, but we also could not find a small library to save it. :slight_smile: (Please let us know if we missed a good option.)

One more comment: the difference between our diagnostic types is a reflection of the difference between LSP and Rust, the two major camps. asai mostly follows LSP and Grace mostly follows Rust. :slight_smile: For most cases, it should be possible to convert diagnostics back and forth without losing much information.

1 Like