Well-Typed Blog https://well-typed.com/blog/ Because Well-Typed Programs Don't Go Wrong en Thu, 08 Oct 2026 00:00:00 GMT Thu, 08 Oct 2026 00:00:00 GMT Well-Typed Blog Generator https://well-typed.com/img/wtnlogoplain.svg Well-Typed Blog https://well-typed.com/blog/ Because Well-Typed Programs Don't Go Wrong First official release of hs-bindgen https://well-typed.com/blog/2026/10/hs-bindgen-official-release edsko hs-bindgen open-source foreign function interface http://www.well-typed.com/blog/2026/10/hs-bindgen-official-release Thu, 08 Oct 2026 00:00:00 GMT Well-Typed and the entire hs-bindgen team—there are quite a few of us, see below—are delighted to announce hs-bindgen 1.0, the first official release. In case you missed the announcement of the alpha release, hs-bindgen is a tool to automatically generate Haskell bindings from C headers.

In this blog post we will start with a very brief intro to hs-bindgen, but we will not repeat everything that we discussed in the first two blog posts that announced the first and second alpha releases. Instead, we will highlight a few of the major changes; for a full list (which is quite long!), please see the changelog.

You can find hs-bindgen on Hackage.

Introduction

Consider this small C header:

#include <stddef.h>

typedef size_t length;

typedef struct str {
  char* bytes;
  length len;
} str;

/**
 * Construct \ref str from null-terminated input
 */
str new_string(const char* str);

When we run hs-bindgen on this example

$ hs-bindgen-cli preprocess example.h --omit-field-prefixes # .. more args

it will generate a number of Haskell modules, which we summarize below:

newtype Length = Length{
    unwrap :: CSize
  }

data Str = Str{
    bytes :: Ptr CChar
  , len   :: Length
  }

-- .. bunch of instances ..

{-| Construct 'Str' from null-terminated input

    __C declaration:__ @new_string@
    .. other Haddocks elided, here and elsewhere ..
-}
new_string ::
     PtrConst CChar -- ^ __C declaration:__ @str@
  -> IO Str
new_string = {- .. -}

Some notable features:

  • C names are translated into Haskell names, modifying them to match Haskell’s naming rules where needed.
  • With --omit-field-prefixes the Haskell code relies on DuplicateRecordFields; without that option it would have prefixed every field (lengthUnwrap, strBytes, etc.).
  • No Haskell definition is generated for size_t, defined in stddef.h; instead, it is mapped to the existing CSize type by means of a binding specification for the standard C library. Binding specifications make binding generation compositional: bindings generated for one library can be reused in another.
  • The length typedef is translated to a Haskell newtype, but the str typedef around the str struct is not: the latter exists in C only for syntactic convenience.
  • Function new_string returns a struct by value, which is not natively supported by Haskell’s FFI, and so hs-bindgen will also generate the necessary C wrappers.
  • All Haskell declarations get Haddock comments linking them to the corresponding C declaration; if that C declaration has associated Doxygen comments, those are also translated.

In the remainder of this blog post we will highlight some of the improvements we’ve made since the alpha release. As you will see, there are a lot of details to get right!

FFI types

Consider a C function

void foo(MyType x)

The obvious translation into Haskell is

foreign import {- .. -} foo_wrapper :: MyType -> IO ()

However, this is valid only if GHC can see that MyType is a type supported by the Haskell FFI; in particular, this means that GHC must be able to unwrap that MyType newtype until it gets a base type from a fixed set of permitted foreign types.

This is hard to ensure in general, especially if MyType is not newly generated, but comes from another library (previously generated by hs-bindgen, or handwritten). In the alpha release we resolved this by reducing every argument to a base type, but this resulted in code that was less portable than it could have been; for example, we might use Int32 instead of MyType.

We now solve this in a better way: given a Haskell type corresponding to a C type, a binding specification can (and should) specify an “FFI type” for that Haskell type: an FFI type is a pair of a module M and type F such that F is legal to appear in a foreign import in a context where M is in scope. For example, Foreign.C.CSize is an FFI type, because CSize can appear in a foreign import if Foreign.C is imported: Foreign.C exports all the necessary newtype constructors.

The translation from MyType to its FFI type (which might be MyType itself) is now also more general; MyType just needs to have an instance of the HasFFIType type class:

class HasFFIType a where
  type FFIType a :: Type

  toFFIType   :: a -> FFIType a
  fromFFIType :: FFIType a -> a

The FFIType type instance should line up with the FFI type specified in the binding spec. In many cases, toFFIType and fromFFIType can simply be coerce.

As an example, if MyType’s FFI type is CSize, then hs-bindgen will generate code

foreign import {- .. -} foo_wrapper :: CSize -> IO ()

foo :: MyType -> IO ()
foo x = foo_wrapper (toFFIType x)

In general the bindings generated by hs-bindgen are still specific to the specified target platform (the host, by default), but the introduction of FFI types reduces an avoidable source of non-portability.

Unnamed declarations

In Haskell, we might define a binary tree with values in the leaves as

data BTree a = Leaf a | Branch (BTree a) (BTree a)

An analogous definition in C might look something like this:

enum tag {LEAF, BRANCH};

struct BTree {
  enum tag constr;
  union {
    int value;
    struct {
      struct BTree* left;
      struct BTree* right;
    } branch;
  };
};

The union is anonymous: in C, its fields are accessed as if they are fields of the parent (struct BTree). In addition, the inner struct is unnamed, although the field of the union in this case does have a name (branch).

Haskell does not have anonymous records or anonymous sums, and so we must choose names. We have a policy in hs-bindgen to never generate numbered names (“struct 1”), and instead pick names based on surrounding clues, to avoid the generated code changing in unpredictable ways when the C headers change. In this case, the union is named after its first field and its parent: BTree_anon'value; similarly the struct is named after its parent and the name of the field: BTree_anon'value_branch. The anon' infix avoids name clashes with other generated names (C names cannot contain ticks).

newtype Tag = Tag CUInt
pattern LEAF, BRANCH :: Tag

data BTree = BTree{
    constr     :: Tag
  , anon'value :: BTree_anon'value
  }

newtype BTree_anon'value = ..

instance HasField "value"  BTree CInt
instance HasField "branch" BTree BTree_anon'value_branch

instance HasField "value"  (Ptr BTree) (Ptr CInt)
instance HasField "branch" (Ptr BTree) (Ptr BTree_anon'value_branch)

data BTree_anon'value_branch = BTree_anon'value_branch{
    left  :: Ptr BTree
  , right :: Ptr BTree
  }

These names are perhaps a bit awkward, but in most cases code never has to deal with them, because hs-bindgen generates “indirect” HasField instances that make it possible to treat the fields of the union as if they are fields of the parent, just like in C. Moreover, we have these instances also for pointers; this means that when using the OverloadedRecordDot extension, we can write Haskell code that processes these C values in a very natural way:1

toBTree :: Ptr C.BTree -> IO (BTree CInt)
toBTree bt = do
    tag <- peek bt.constr
    case tag of
      C.LEAF ->
        Leaf <$> peek bt.value
      C.BRANCH -> do
        left  <- peek bt.branch.left
        right <- peek bt.branch.right
        Branch <$> toBTree left <*> toBTree right

Improved record-dot support

Although support in GHC for overloaded record update is sadly not yet as polished as overloaded record access, it can nonetheless be quite helpful when dealing with C code that uses a lot of unions: unions don’t have a natural representation in Haskell, and hs-bindgen therefore encodes them as opaque datatypes.

To continue the example from the previous section, we can construct a value of type BTree as

import HsBindgen.Runtime.Union qualified as Union

btree1 :: C.BTree
btree1 = C.BTree{
      constr     = C.BRANCH
    , anon'value = Union.zero{
          branch = C.BTree_anon'value_branch{
              left  = nullPtr
            , right = nullPtr
            }
        }
    }

If we take advantage of the indirect fields described in the previous section, we can improve this further:

import HsBindgen.Runtime.Struct qualified as Struct

btree2 :: C.BTree
btree2 = Struct.zero{
     constr = C.BRANCH
   , branch = Struct.zero{
         left  = nullPtr
       , right = nullPtr
       }
   }

Note that OverloadedRecordUpdate currently also requires RebindableSyntax; hs-bindgen-runtime provides a module HsBindgen.Runtime.Overloading that restores the standard environment. See also Enabling record dot syntax in the manual.

Macros

Preprocessor macros are used extensively in C development, and so for many applications it is important they too get translated to Haskell. Macro handling in hs-bindgen has been significantly improved since the alpha. Most of those changes are internal, though they will become user-facing once we release hs-bindgen-as-a-library, at which point it will also be possible to substitute your own macro languages, replacing hs-bindgen’s default c-expr.

The full list of improvements can be found in the changelog; here we will mention just a few. First, we can now parse declarations that use a mixture of macros we can parse and macros that we cannot. For example, given

#define DeviceId int
#define MUST_CHECK __attribute__((warn_unused_result))

int upgradeFirmware(DeviceId did) MUST_CHECK;

where the definition of DeviceId is parsed by hs-bindgen but the definition of MUST_CHECK is not, we now generate

newtype DeviceId = DeviceId CInt
upgradeFirmware :: DeviceId -> IO CInt

Second, detection of ambiguous macros (macros that do not have a unique expansion throughout the translation unit) is improved. For example, given

#define A 5
#define B A
#define B A

#define X 1
#define Y X
#undef X
#define X 2
#define Y X

we generate bindings for A and B

a :: CInt
a = 5

b :: CInt
b = a

but not for X and Y.

Finally, macros can now be defined as part of the input to hs-bindgen (--hash-define FOO 1). Previously such definitions had to be given twice, once to hs-bindgen and once to the C compiler via ghc-options: -optc-DFOO, which was easy to get wrong and could be hard to debug.

Conclusions

Although Haskell’s foreign function interface is good, writing bindings to large C libraries is nonetheless a laborious process. The “fire and forget” approach that hs-bindgen offers takes care of a lot of the legwork. We’re pretty proud of the fact that hs-bindgen can handle almost everything that a C header might throw at it.

However, for many applications the bindings generated by hs-bindgen will be a starting point only: they are a direct translation of the C code, and are therefore very low-level. We are working on a binding-combinators library that makes this process easier, but ultimately such high-level bindings are then still written by hand, albeit assisted by a library. The next big goal for hs-bindgen is automatic generation of high-level bindings, guided by pluggable heuristics.

It has taken a lot of effort to get here, and we thank Anduril for sponsoring this work. Within Well-Typed, the hs-bindgen team includes or at one point included Armando Santos, Dominik Schrempf, Edsko de Vries, Finley McIlwaine, Joris Dral, Matthias Heinzel, Oleg Grenrus, Sam Derbyshire and Travis Cardwell. We have also benefited from numerous contributions from external contributors in the form of issues and PRs, for which we are grateful!

hs-bindgen 1.0 is available on Hackage now; give it a spin and let us know if you have any problems!

  1. This assumes a prescriptive binding spec to tell hs-bindgen to mark the tag as closed, causing hs-bindgen to generate a COMPLETE pragma. See #2101.↩︎

]]> Memory profiling of large Haskell applications with ghc-debug https://well-typed.com/blog/2026/10/memory-profiling-large-haskell-applications-with-ghc-debug hannes well-typed ghc ghc-debug community memory mercury profiling http://www.well-typed.com/blog/2026/10/memory-profiling-large-haskell-applications-with-ghc-debug Fri, 02 Oct 2026 00:00:00 GMT ghc-debug is a debugging tool for performing precise heap analysis of Haskell programs (for more background, check out our previous post improving ghc-debug and the Case Study: Debugging a Haskell space leak). While doing some memory profiling for Mercury, we took the opportunity to make some much needed improvements and quality of life fixes to both the ghc-debug set of libraries and the ghc-debug-brick terminal user interface.

The 0.8 releases focused on improving responsiveness and usability on very large memory profiles. In particular, ghc-debug now streams intermediate profile results, giving immediate feedback for huge heap traversals.

To summarise the improvements to ghc-debug-brick, it now:

  • shows partial results, and allows heap traversals to be stopped at any moment without losing existing results;
  • implements history navigation, allowing you to switch between heap profile views; and
  • improves the decoding of stack frames and shows stack annotations.

Streaming of intermediate results

The ghc-debug-brick TUI is the starting point for any memory profiling with ghc-debug. It provides useful heap traversal features, for example finding closures with certain properties (via an expressive filter system), summarising all live heap objects, or analysing thunk origins.

Most of these features need to traverse the full heap to provide a conclusive result. A summary of all live heap objects cannot be complete until the full heap has been traversed. This works fine for smaller heaps, but what if the program heap is really big? Say, more than half of system RAM? The full heap traversal will take a long time, or even worse never finish, as it may use more memory than the system can provide.

To make ghc-debug usable with large heaps, we added support for streaming of results as they come in. No more waiting around: seconds after you start the heap traversal, the first results are shown on the screen. While you wait for more results, you can interact with the profile in a limited way. If you think you’ve gathered enough data, you can stop the heap traversal by pressing ESC and then explore retainers and fields, or start a different heap traversal.

Note that a stopped traversal can’t be resumed, and you have to start from scratch to find more results. There are currently no plans to add support for resuming a stopped traversal, as this would be complex to implement and can quickly leak a lot of memory when accumulating multiple partial queries.

All ghc-debug-brick heap traversals support this form of streaming/incremental results. While ghc-debug can be slow because the heap traversals are slow, it now feels much more responsive and more rewarding to work with large heaps.

Incremental results of a heap traversal

History navigation

Heap traversals are expensive and take time, but ghc-debug-brick had only one view: the result of the last heap traversal. This was a constant source of frustration when analysing huge heaps, making it tedious to make progress. We improved this by adding a history for finished (and partial) heap traversals. You can view the history by pressing Ctrl+r, or via the command picker, and see the results of previous queries.

The history can be navigated with Alt+Left Arrow to go back in history or Alt+Right Arrow to go forward again.

View the history of heap traversals

Stack decoding

We improved the stack frame decoding logic of ghc-debug considerably, adding support for underflow frames, fixing InfoTable decoding and tidying up the rendering. Similar to other heap closures, stack frames have source locations (info table provenance entries) attached, which help with identifying where a particular stack frame or heap object was allocated.

Stack frames themselves can be retainers of heap objects, so improving ghc-debug’s support for stack frame decoding was much-needed.

Stack Frame decoding of Stack Trace annotated with source location labels

Stack annotations

We added support for stack annotations in supported GHC versions to ghc-debug. These allow the user to annotate the native Haskell execution stack with additional metadata, such as additional context about the current location in the source program. Naturally, we taught ghc-debug how to decode stack annotation frames and display them as well.

As stack annotations are themselves merely heap objects, they are represented as SomeStackAnnotation closures that you can further drill into. Unfortunately, the annotations themselves can’t be displayed simply via the usual displayStackAnnotation rendering function, as this might evaluate thunks and change the Haskell heap.

Stack annotations help to understand complicated computation flows by adding user-defined instrumentation to the RTS stack. They were crucial in identifying multiple bugs in ghc-debug’s stack frame decoding logic.

Stack Frame decoding containing Stack Annotation Frames

Conclusion

We hope that the improvements to ghc-debug and ghc-debug-brick will aid the workflows of anyone looking to perform detailed inspections of the heap of their Haskell processes. The improvements should especially benefit anyone who works with large heaps. The new features have all been released to Hackage in ghc-debug-brick-0.8.

This work has been performed in collaboration with Mercury. Mercury have a long-term commitment to the scalability and robustness of the Haskell ecosystem and are supporting the development of memory profiling tools to aid with these goals.

Well-Typed are always interested in projects and looking for funding to improve GHC and other Haskell tools. Please contact info@well-typed.com if we might be able to work with you!

  1. Frame 0 is the top of the stack, while Frame 23 is the bottom, indicated by the STOP_FRAME which is always the first stack frame on the GHC RTS stack.↩︎

]]> Real-Time Telemetry with Eventlog Live https://well-typed.com/blog/2026/09/real-time-telemetry-with-eventlog-live wen open-source telemetry performance profiling http://www.well-typed.com/blog/2026/09/real-time-telemetry-with-eventlog-live Thu, 24 Sep 2026 00:00:00 GMT Well-Typed are happy to announce Eventlog Live, a program that streams real-time telemetry from any Haskell application to any observability platform that supports the OpenTelemetry protocol, such as Grafana Cloud, Prometheus, or local viewers such as otel-tui and otel-desktop-viewer.

In this blog post, we’ll show a variety of ways to use Eventlog Live. For each showcase, we’ll link to the relevant instructions using Eventlog Live version 0.10.0.0 as well as the script that was used to generate the showcase. If you would like to use Eventlog Live, we recommend following the up-to-date instructions in the README of the latest release of Eventlog Live.

Heap Profiles by Closure Type

An animated GIF that shows a screen recording of a Grafana dashboard called Heap Profiles. It shows the heap profile of the example program called 'oddball', which has highly volatile memory usage. The dashboard has several configuration options, which let you select the service name and instance ID. For the example, the selected service name and instance ID are 'oddball' and a generated UUID, respectively. The dashboard is configured to show the last 5 minutes of data and refresh every 5 seconds. The dashboard is split into two columns. The left column contains a stacked area graph labelled 'Heap Profile' that shows a heap profile broken down by closure type. Below, there are three buttons labelled 'Start', 'Stop', and 'Census'. The right column contains six visualisations in a two-by-three grid. In order, these are labelled 'Heap Size', 'Memory Management', 'Heap Copied per GC by Generation', 'Heap Fragmentation by Generation', 'Heap Slop by Generation', and 'Heap Allocation by Capability'. The 'Heap Size' visualisation is a bar chart that shows three metrics. The 'Allocated from OS' metric shows the current size of the heap measured in megablocks, which is the unit in which the GHC RTS requests memory from the OS. The 'Allocated' metric shows the current size of the heap measured in blocks, which is the subunit that the GHC RTS uses to dole out memory to the application. The 'Live' metric shows the current size of the live heap, measured in live blocks. All three measurements are visualised in bytes. The 'Memory Management' visualisation shows three metrics that track the interaction with the OS: 'Current', 'Needed', and 'Returned'. The 'Current' metric shows the number of megablocks currently held by the RTS. The 'Needed' metric shows the number of megablocks that the RTS currently needs. If 'Needed' exceeds 'Current', the RTS is about to request more memory from the OS. If 'Needed' is less than 'Current', the RTS should return the excess megablocks to the OS. If this happens, the number of returned megablocks is shown in the 'Returned' metric. The 'Heap Copied per GC by Generation', 'Heap Fragmentation by Generation', and 'Heap Slop by Generation' are bar charts that show the number of bytes copied during GC, the amount of heap fragmentation found during GC, and the amount of slop bytes found during GC, respectively. These metrics are broken down by heap generations. In the example, these are Generation 0 and Generation 1. The 'Heap Allocation by Capability' visualisation is a bar chart that shows the number of bytes allocated by each capability. This metric is broken down by capability, but in the example there is only one Capability.

The Grafana Heap Profiles dashboard, which shows a heap profile broken down by closure type (-hT) as well as a variety of metrics for memory usage. For detailed instructions, see Eventlog Live – The Basic Version. This showcase uses the oddball-with-pipe example with the Docker Compose setup in demo/docker-compose.yml.

Eventlog Live

Eventlog Live analyses your application’s eventlog and exports it via the OpenTelemetry protocol. Eventlog Live is lightweight, runs side-by-side with your application in only a few megabytes of memory, and requires no instrumentation other than the -threaded and -rtsopts build options.1 All you need is somewhere to send your data. For instance, if you have a Grafana Cloud2 account, adding telemetry to your application is as easy as:

# Create a pipe for the eventlog
EVENTLOG_PIPE="/tmp/eventlog.pipe"
mkfifo "${EVENTLOG_PIPE}"

# Start your application
your-application +RTS -l -ol"${EVENTLOG_PIPE}" -hT --eventlog-flush-interval=1 -RTS &

# Start eventlog-live-otlp
OTEL_SERVICE_NAME="your-application"                                              \
OTEL_RESOURCE_ATTRIBUTES="service.instance.id=$(uuidgen)"                         \
OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-<YOUR_REGION>.grafana.net/otlp" \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic%20<YOUR_AUTHORIZATION_HEADER>"    \
eventlog-live-otlp --eventlog-file="${EVENTLOG_PIPE}" -hT --eventlog-flush-interval=1

Out of the box, Eventlog Live supports -hT and -hi heap profiles3 as well as a variety of memory usage metrics, cost-centre stack profiles, log messages, productivity, detailed thread & capability usage traces. Each of these features is showcased below using an example Grafana dashboard. These dashboards can be found in the repository under demo-grafana-cloud/grafana-dashboards and demo/config/grafana-dashboards. Click any showcase for more information.

Heap Profiles by Info Table

An animated GIF that shows a screen recording of the same Heap Profiles dashboard as under Heap Profiles by Closure Type, except that the categories for each heap profile sample show more detailed information based on the info tables.

The Grafana Heap Profiles dashboard, which shows a variety of metrics for memory usage and a heap profile broken down by info table (-hi). For detailed instructions, see Eventlog Live with Heap Profiling by Info Table. This showcase uses the oddball-with-hi example with the Docker Compose setup in demo/docker-compose.yml.

Cost-Centre Stack Profiles

An animated GIF that shows a screen recording of a Grafana dashboard called Cost-Centre Stack Profiles. The dashboard has several configuration options, which let you select the service name and instance ID. For the example, the selected service name and instance ID are 'jumpy-jump' and a generated UUID, respectively. The dashboard is configured to show the last 6 hours of data and refresh every 5 seconds. The dashboard has one visualisation, which is split into two columns. The left column shows a table of symbols together with their sample count. The top two samples are IDLE and SYSTEM, followed by uniformIntegralM, an ever-changing list of ten functions called jumpyJump0 to jumpyJump9, and, occasionally, PROFILING:OVERHEAD_OF. The right column shows the stack profile as a flame graph. (Technically, an icicle chart, since the spikes go downward, but I don't think people use that word much anymore.) The flame graph is dominated by the IDLE category, which is sampled, roughly, two orders of magnitude more often than every other category.

The Grafana Cost-Centre Stack Profiles dashboard, which shows the cost-centre stack samples collected by GHC's built-in profiler in a flame graph. For detailed instructions, see Eventlog Live with Cost-Centre Stack Profiling. This showcase uses the jumpy-jump-with-cost-centre-profiler example with the Docker Compose setup in demo/docker-compose.yml.

Logs

An animated GIF that shows a screen recording of a Grafana dashboard called Logs. The dashboard has several configuration options, which let you select the service name and instance ID. For the example, the selected service name and instance ID are 'oddball' and a generated UUID, respectively. The dashboard is configured to show the last 6 hours of data and refresh every 5 seconds. The dashboard has one visualisation, which shows a list of log messages with their time and severity. Each log message has the TRACE severity and is some variant of 'Summing 313172 numbers', except the first two messages which are the thread labels for the timer and IOManager threads emitted by the RTS.

The Grafana Logs dashboard, which shows log messages emitted using traceEventIO, traceMarkerIO, and threadLabel. This showcase uses the oddball-with-pipe example with the Docker Compose setup in demo/docker-compose.yml.

Logs as Markers

An animated GIF that shows a screen recording of the same Heap Profiles dashboard as under Heap Profiles by Info Table. However, in the configuration options a switch labelled UserMarker is enabled and the field labelled Filter UserMarker contains the regular expression 'Summing \d+ numbers', and each visualisation shows dotted red lines at the times that correspond to these markers.

The Grafana Heap Profiles dashboard, which shows dotted red lines on each visualisation at the times that correspond to the markers, emitted using traceMarkerIO, that match the regular expression Summing \d+ numbers. This showcase uses the oddball-with-hi example with the Docker Compose setup in demo/docker-compose.yml.

Productivity

An animated GIF that shows a screen recording of a Grafana dashboard called Threads. The dashboard has several configuration options, which let you select the service name and instance ID. For the example, the selected service name and instance ID are 'oddball' and a generated UUID, respectively. The dashboard is configured to show the last 5 minutes of data and refresh every 5 seconds. The dashboard is split into two columns. In the left column, there is a bar chart labelled 'Productivity by Capability', which shows the ratio between executing user code and garbage collection as a percentage, split out by capability and summed over the entire execution. Oddball uses only one capability, Capability 0. From the bar chart, we can see that this capability is about 80% productive during the first few seconds, then nosedives to about 65%, and stays there for the remainder of the animation. In the right column, there is a stacked area graph labelled 'Capability Usage', which shows the capability usage over a sliding window, split out into executing user code (labelled 'Mutator'), garbage collection (labelled 'GC'), and idle time (labelled 'Idle'). While this affirms the image shown by the previous visualisation, it reveals that oddball is idle the vast majority of the time.

The Grafana Threads dashboard, which shows the cumulative productivity per capability, as well as the overall productivity over a sliding window. This showcase uses the oddball-with-pipe example with the Docker Compose setup in demo/docker-compose.yml.

Thread & Capability Usage

A screenshot that shows the Grafana Trace Explorer, which is currently exploring a thread usage trace for thread 3. Each span is listed with its type (either Running or Blocked) and its duration. One particular span is selected, which unfolds the entry and reveals more information. Notably, it reveals that thread 3 was blocked during this span due to a foreign function call.

Eventlog Live’s OTLP exporter is configured using OpenTelemetry’s environment variables. The output of eventlog-live-otlp --help has comprehensive documentation on its support for these environment variables. By default, Eventlog Live aggregates telemetry data over 1 second intervals and exports every 30 seconds, but these intervals can be configured for each telemetry signal using configuration files.

Dynamic Control with Eventlog Socket

If you instrument your application with eventlog-socket, you’ll be able to start/stop profiling while your application is running using a REST API, which you can connect, e.g., to buttons on your Grafana dashboard, as we’ve done on the example Heap Profiles dashboard.

Dynamic Control with Eventlog Socket

An animated GIF that shows a screen recording of the same Grafana Heap Profiles dashboard that was described above. It continues to show the heap profile of the 'oddball' example program. This recording illustrates the usage of the 'Start' and 'Stop' buttons. At the start of the recording, the 'Heap Profile' visualisation shows a history of volatile and spiky memory usage. After a few refreshes, the 'Stop' button is pressed, the message 'Requested Heap Profiling Stop' appears in the top-right corner, and the 'Heap Profile' visualisation flatlines. A few refreshes later, the 'Start' button is pressed, the message 'Requested Heap Profiling Start' appears in the top-right corner, and the 'Heap Profile' visualisation resumes. The 'Census' button can be used to request a single heap census, though this isn't shown in the recording. The visualisations in the right column are unaffected by the 'Start' and 'Stop' button, and continue to update during the entire recording.

Using the buttons on the Grafana Heap Profiles dashboard. When “Stop” is pressed, the heap profile flatlines. When “Start” is pressed, the heap profile resumes. The “Census” button can be used to request a single heap census. For detailed instructions, see Eventlog Live with Eventlog Socket. This showcase uses the oddball-with-hT example with the Docker Compose setup in demo/docker-compose.yml.

Eventlog Socket lets your application write its eventlog over sockets and uses the other direction of communication for control messages. Eventlog Socket’s control protocol is generic. It isn’t bound to any specific application or library. Any library can register its own control commands under its own namespace,4 using Haskell IO actions as callbacks:

registerMyEventlogSocketSupport = do
  myPackageNamespace <- registerNamespace "my-package-name"
  registerCommand myPackageNamespace (CommandId 1) myCommandCallback1
  registerCommand myPackageNamespace (CommandId 2) myCommandCallback2

Any command that your application registers with Eventlog Socket can be invoked using Eventlog Live’s REST API.

For security reasons, Eventlog Socket’s control protocol and Eventlog Live’s REST API are hidden behind the +control feature flag, which is disabled by default. If you develop a library that (optionally) uses Eventlog Socket’s control protocol, we recommend using the same +control feature flag.

Call-Stack Profiles with GHC Stack Profiler

If you instrument your application with ghc-stack-profiler, you’ll be able to use its lightweight call-stack profiler.

Call-Stack Profiles with GHC Stack Profiler

An animated GIF that shows a screen recording of a Grafana dashboard called Call-Stack Profiles. This dashboard has the same layout as described under Cost-Centre Stack Profiler, but the profiles are slightly different. Notably, the IDLE, SYSTEM, and PROFILING:OVERHEAD_OF categories are not recorded by GHC Stack Profiler. The most prevalent category is 'other' followed by the same ever-changing list of ten functions called jumpyJump0 to jumpyJump9. The flame graph is significantly spikier. The IDLE category isn't recorded and does not dominate the flame graph, which leaves a lot more room for the deeply nested calls jumping between the various jumpyJump functions.

The Grafana Call-Stack Profiles dashboard, which shows the call-stack samples collected by ghc-stack-profiler in a flame graph. For detailed instructions, see Eventlog Live with GHC Stack Profiler. This showcase uses the jumpy-jump-with-ghc-stack-profiler example with the Docker Compose setup in demo/docker-compose.yml.

GHC Stack Profiler samples GHC’s runtime call-stack, rather than a virtual cost-centre stack, and writes these samples to the eventlog. Based on our benchmarks, GHC Stack Profiler has virtually no overhead when it’s not running and we observed 2-8% overhead while it was running, compared to GHC’s built-in cost-centre stack profiler, where we observed 54-128% overhead while it wasn’t running and 98-136% overhead while it was running.

If you’ve also instrumented your application with Eventlog Socket, you’ll be able to start/stop GHC Stack Profiler while your application is running using the same REST API, which you can connect, e.g., to buttons on your Grafana dashboard, as we’ve done on the example Call-Stack Profiles dashboard.

GHC Stack Profiler can also be used without Eventlog Live, e.g., by exporting the profiles to speedscope. We’ll discuss GHC Stack Profiler in detail in an upcoming blog post.

Local Viewers

Eventlog Live does not yet include a built-in telemetry viewer, as it was primarily developed to monitor long-running processes in production. We are currently developing a built-in telemetry viewer, but the prototype is not yet ready for publication. In the meantime, some developers may feel that using either Grafana Cloud or the Docker Compose setup in demo/docker-compose.yml is too heavyweight for local development. Fortunately, the OpenTelemetry ecosystem has several lightweight telemetry viewers, such as otel-tui and otel-desktop-viewer, which are general purpose telemetry viewers that use a text and browser-based UI, respectively.

Eventlog Live with otel-tui

An animated GIF that shows a screen recording of a terminal session. The terminal is split into three screens. On the left, taking up the majority of the terminal, is a screen labelled 'otel-tui'. On the right, split vertically, are two screens labelled 'oddball' and 'eventlog-live-otlp'. The 'otel-tui' screen is itself split into three subscreens. A narrow column on the left, labelled 'Metrics', lists all incoming metrics by name. These names correspond to the names described under Heap Profile by Closure Type, except formatted in camel-case and prefixed with 'ghc_eventlog_'. Currently, the metric named 'ghc_eventlog_HeapLive' is selected. The wide column on the right is split vertically. The top row, labelled 'Details', shows the exact structure of the selected OTLP message for the selected metric. The bottom row, labelled 'Chart', shows a text rendering of a line chart that shows the values of the 'ghc_eventlog_HeapLive' metric. This shows a spiky line, which jumps between 10-30MB, though the Y-axis is labelled in bytes rather than megabytes. The 'oddball' screen shows the output of the oddball program, which consists of many lines saying 'Generating X random numbers' and 'Sum: Y' for ever-changing values of X and Y. The 'eventlog-live-otlp' screen shows the debug output of Eventlog Live, which consists of many lines saying '[DEBUG] Received X events.', '[DEBUG] Exported Y metrics.', and '[DEBUG] Exported Z logs.', for ever-changing values of X, Y, and Z.

This showcase uses the oddball-with-otel-tui example with otel-tui version 0.7.4. This example creates a screen session that combines otel-tui with oddball and eventlog-live-otlp.

Eventlog Live with otel-desktop-viewer

An animated GIF that shows a screen recording of the browser-based otel-desktop-viewer application. The website is split into three columns. The left column has three tabs labelled 'Traces', 'Metrics', and 'Logs'. Currently, the 'Metrics' tab is selected, which lists all incoming metrics by name and application. These names correspond to the names described under Heap Profile by Closure Type, except formatted in camel-case and prefixed with 'ghc_eventlog_'. Currently, the metric named 'ghc_eventlog_HeapProfSample (oddball)' is selected. The right column lists all series in this metric. The 'ghc_eventlog_HeapProfSample' metric is the heap profile, broken down by closure type, so the various series correspond to the various closure types. Only the top few series are selected. Amongst these are built-in closure types such as FUN, FUN_2_0, STACK, and BLACKHOLE, as well as user-defined function types such as ghc-bignum:GHC.Num.Integer.IS. The series are constantly reordered, so they're a bit hard to read. The middle column, which takes up about half of the website, shows a chart with the selected series. While ten series are selected, only two lines are visible. STACK and ghc-bignum:GHC.Num.Integer.IS. This is because these samples represent the vast majority of the heap size used by the oddball program. The remaining lines, presumably, all hug the X-axis, though this isn't visually clear.

This showcase uses the oddball-with-otel-desktop-viewer example with otel-desktop-viewer version 0.5.0.

Future Work

We are currently developing a built-in telemetry viewer that is purpose-built for GHC’s telemetry, with the intention of making Eventlog Live more useful for short development sessions. We’re also planning to create a library for writing structured log messages to the eventlog, expand the analyses supported by Eventlog Live, and expand the Eventlog Socket protocol to permit command arguments. Moreover, we’re always open to suggestions and feature requests from the community.

Acknowledgements

This work has been performed in collaboration with Mercury, who have a long-term commitment to the scalability and robustness of the Haskell ecosystem. Well-Typed are always interested in projects and looking for funding to improve Haskell tools. Please contact info@well-typed.com if we might be able to work with you!

  1. If your application is built with GHC 9.2 or older, it must also be built with -eventlog. Since GHC 9.4, the eventlog is enabled by default.↩︎

  2. The repository contains a self-contained demo for using Eventlog Live with Grafana Cloud. Unfortunately, as Grafana Cloud changes its user interface frequently, that demo may not be fully up-to-date.↩︎

  3. Eventlog Live is developed and tested with the -hT and -hi heap profile breakdowns, but the -hm/-hd/-hy/-he heap profile breakdowns should work. The -hc/-hb/-hr heap profile breakdowns require additional support, which is planned but not yet implemented.↩︎

  4. We strongly recommend using your package name.↩︎

]]> Haskell ecosystem activities report: June–August 2026 https://well-typed.com/blog/2026/09/haskell-ecosystem-report-june-august-2026 adam, alex, andrea, andreask, ben, davide, duncan, hannes, magnus, mikolaj, rodrigo, sam, tobias, wen, wolfgang, zubin well-typed ghc community haskell-ecosystem-report http://www.well-typed.com/blog/2026/09/haskell-ecosystem-report-june-august-2026 Fri, 18 Sep 2026 00:00:00 GMT This is the thirty-second edition of our Haskell ecosystem activities report, which describes the work Well-Typed are doing on GHC, Cabal, HLS and other parts of the core Haskell toolchain. The current edition covers roughly the months of June, July and August 2026.

You can find the previous editions collected under the haskell-ecosystem-report tag.

Sponsorship

We offer Haskell Ecosystem Support Packages to provide commercial users with support from Well-Typed’s experts while investing in the Haskell community and its technical ecosystem including through the work described in this report. To find out more, read our announcement of these packages in partnership with the Haskell Foundation. We need funding to continue this essential maintenance work!

Many thanks to our Haskell Ecosystem Supporters: Standard Chartered, Channable and QBayLogic, as well as to our other clients who also contribute to making this work possible: Anduril, Juspay and Mercury; and to the HLS Open Collective for supporting HLS release management.

Highlights

Known-key names and reinstallable base

We have long been working to decouple GHC from base, to make it easier to upgrade the compiler independently from the (standard) libraries. A key restriction that prevented disentangling base from GHC was GHC’s treatment of known entities. These are things in the standard libraries that GHC needs to know something about (e.g. Show for deriving, Monad for desugaring do notation, etc). This is detailed in section 3.3 of a recent blog post by Simon Peyton Jones.

Rodrigo and Sam recently overhauled GHC’s treatment of known entities, in collaboration with Simon (!15899), finally landing the patch in August. This allowed known entities to be defined completely outside of the compiler for the first time, without hard-coding the precise module that defines them.

As part of this change, it was also necessary to rework some implementation details of Typeable, namely the KindRep datatype. Sam opened CLC proposal #433 to get approval on this change, which required an accompanying change to the binary package, which Rodrigo implemented in #244.

AArch64 code generation and sub-word handling

Andreas has been hunting down a slew of correctness bugs in the AArch64 native code generator, mostly related to the handling of sub-word values. Issues include sub-word handling across C calls (#27430), in atomic loads/stores (#27533), in conversions (#27537), in if conditionals (#27538), in %i2f64 (#27539) and the use of invalid immediates (#27550). These were all fixed in !16255, with a lot of the testing infrastructure being provided by Sam’s overhaul of test-primops (!43).

Coercion zapping

Extremely poor compiler performance for programs involving significant type-level computation has long plagued the community (#8095, recently re-reported as #27336). One major cause for this is blow-ups in coercion sizes due to the representation of accumulated type family reduction steps in Core, GHC’s typed intermediate language.

This problem resisted many attempts over the years, with promising approaches being brought down by performance regressions on certain types of programs (e.g. singleton-heavy programs). However, the future is bright for type-level wizards: MR !16378 implementing coercion zapping promises to bring the story to a satisfying conclusion.

This MR has an unusual history. In July, Sylvain Henry put up a proof-of-concept patch that was generated using Claude Fable. This patch was a carefully balanced “best of” previous approaches over the years, combining elements from MRs by Ben (!611), Adam (!6476), Sam (!7787) and Richard Eisenberg (!7909), each of which made significant progress on some programs but struggled to overcome significant compiler performance regressions on other programs.

Sam took over this patch and rewrote it from the ground up, doing a deep dive into GHC’s type family rewriter, and finding several related optimisation opportunities (e.g. !16479).

The net result is a patch that significantly improves compilation speed of type-family-heavy programs without regressing elsewhere. This patch is under final review and we hope to land it soon. Performance results from GHC’s testsuite:

Test case Compiler allocations Compilation time
T8095   768 MB ⇝   128 MB (−83%) 2.432s ⇝ 0.160s (−93%)
T9872a 1 656 MB ⇝ 1 406 MB (−15%) 0.971s ⇝ 0.494s (−49%)
T12545   698 MB ⇝   425 MB (−39%) 0.648s ⇝ 0.387s (−40%)
T13386   428 MB ⇝    35 MB (−92%) 0.259s ⇝ 0.104s (−60%)
T27336   499 MB ⇝    36 MB (−93%) 1.188s ⇝ 0.110s (−91%)
CoOpt_Singletons   634 MB ⇝   596 MB ( −6%) 0.484s ⇝ 0.360s (−26%)
LargeRecord 1 227 MB ⇝   967 MB (−21%) 0.872s ⇝ 0.617s (−29%)
FamAppCachePerf   496 MB ⇝   192 MB (−61%) 0.675s ⇝ 0.191s (−72%)

Exception annotations

Ben’s GHC proposal #330 and accompanying CLC proposal #164 proposed a deep rework of exception backtraces, providing several different backtrace mechanisms (e.g. HasCallStack, profiling cost centres, IPE).

However, the implementation of these proposals remained patchy, as detailed in Edsko’s recent blog post.

The team made several follow-up improvements to mechanisms for attaching information to exceptions:

  • Ben fixed WhileHandling dropping the ExceptionContext of the exception it is handling (!16275, #27456).
  • Sam made sure SomeException does not drop the ExceptionContext of the exception it is storing (!16274, #27455), with accompanying CLC proposal #432.
  • Wolfgang added rethrowSTM (!16501), incorporated the re-export into the stm submodule (!16616), and upstreamed it to stm (#100), with accompanying CLC proposal #436.
  • Zubin made annotateSTM use catchSTM# rather than catch# (!16508), with accompanying CLC proposal #437.

Trees That Grow

Over a long period, GHC has been gradually migrating to the Trees That Grow representation for its internal AST datatypes, and improving the modularity of the AST within the GHC codebase (#19218, #21592). Once complete, this will make it possible to expose the AST in a package that does not depend on the rest of the ghc library, and unblocks doing the same for the parser. As well as improving modularity, this will make it easier to use in tools that parse Haskell syntax, and may unlock future simplifications to template-haskell.

Alex and Rodrigo have been working on the next steps in that process, reorganising the codebase so that there will be no modules in the Language.Haskell.* namespace depending on modules in the GHC.* namespace. This included decoupling Language.Haskell.Syntax from GHC.Hs.Doc (!15601) and from GHC.Types.SourceText (!15573), representing string literals in the AST with Text rather than FastString (#21628, !12846), and decoupling ModuleNames used in the AST from those in GHC (!16546). As part of the original migration strategy, various orphan instances were introduced, which Alex has been cleaning up (#27755, !16299, !16610).

GitLab infrastructure work

Keeping Haskell’s infrastructure available has been increasingly challenging over the past couple of months due to the continued rise in LLM-driven crawling. See for comparison the Creepy crawlies blog post by Konstantin Ryabitsev, detailing the challenges faced by the git hosting infrastructure for the Linux kernel.

The GHC GitLab instance relies on Anubis to reduce crawler traffic. In early August, Magnus traced a fresh surge in load to a crawler that was bypassing Anubis entirely. Blocking it cut the load on the GitLab instance dramatically.

Other important infrastructure items:

  • Magnus and Ben upgraded the instance’s PostgreSQL database, after which Ben carried the GitLab upgrade itself through to the latest release in a single fourteen-hour session. Besides clearing a long-standing backlog item, this made it possible to prioritise traffic from logged-in users.

  • Magnus upgraded the host running the GitLab container, and applied patches to the GitLab instance (e.g. to close certain security vulnerabilities).

GHC

Releases

Frontend

  • Magnus renamed ZonkAny to UnusedType and added pretty-printing logic for it (!16212, #27390), so that it no longer leaks confusingly in HLS output.

  • Magnus refactored the error reporting code for ExplicitLevelImports (!16195).

  • Adam marked various language extension flags as deprecated (!16145), implementing part of the categorisation of language extensions (#27329).

  • Sam relaxed representation-polymorphism restrictions on newtype constructor patterns (!16342, #20363).

  • Sam fixed a couple of issues with mis-oriented coercions produced by GHC (!16474, #27639, !16207, #27374).

  • Sam fixed a crash in the Data.Data instance for HsCtxt (!16142, #27359).

  • Sam reviewed a patch adding explanations for unsolved Typeable constraints (!16351).

Core & simplifier

  • Andreas stopped the specialiser looping on recursive dictionaries in interestingDict (!16559, #27705).

  • Zubin landed various fixes for “Entered absent arg” bugs (!16519, #27627, !16503, #27626), along with fixes for the interaction of absent fillers with speculative evaluation of dictionaries (!16219), following an extensive investigation of the crash reported in #25924.

  • Following on from Simon Peyton Jones’ earlier refactor of GHC.Core.Utils.mkTick (!15494), which Sam helped with, Sam and Magnus tied up several loose ends:

    • preserving tick ordering in tickTickedExpr (!16601), fixing a regression in which source notes were moved past each other;

    • allowing more ticks in argument position in rebuild_app (!16558);

    • stopping ticks being dropped around variables of type IO () (!16123), fixing #27182 and #27225;

    • stopping mkTick in Core Prep from breaking ANF (!16198).

Driver

  • Rodrigo made some improvements to the structure and caching of downsweep (!16330, #27053, #27461).

    During this work, Rodrigo and Sam found an opportunity to clean up some legacy Backpack logic, establishing that implicitRequirementsShallow can never reach a HoleUnit (!16346).

  • Rodrigo deduplicated and shared Modules in interface files (!16216, !16213, #27401).

  • Hannes shared UnitInfos across the UnitEnv using a UnitIndex and an external unit database cache (!16115), and arranged for the UnitIndexCache to be reused after initialising multiple home units (!16598, #27748).

  • Hannes added the backendInfoTableMapValidity backend predicate (!16234).

  • Hannes fixed the order of PackageDBFlags for the interactive home unit (!16591, #27640).

  • Hannes diagnosed the quadratic behaviour of ghc-pkg list (#27275).

  • Zubin carried out a substantial overhaul of the loader (!16493, !16582, !16583) to allow more control over unloading stale linkables, which is useful for HLS to efficiently evaluate expressions as files change in the IDE (#27606).

  • Zubin made UniqDFM.alter preserve insertion order (!16385).

  • Wolfgang finished up a patch sorting Usages by fingerprint, to ensure determinism (!15484).

Code generation

  • Andreas fixed common block elimination silently dropping a procedure’s info table (!16592, #27722).

GHCi and bytecode

  • Wolfgang added --show-byte-code, the counterpart of --show-iface for bytecode files (!16386, #26909).

RTS

  • Duncan continued his sustained work to overhaul RTS I/O managers and the scheduler. One of the main goals is to bring the non-threaded RTS in line with the threaded one (e.g. #27335), and to improve maintainability across I/O manager implementations. As part of this effort, Duncan landed a collection of I/O manager refactors (!16217), preparing the ground for fixing idle GC and deadlock detection on the non-threaded RTS. Duncan also brought the POSIX and Win32 ticker implementations more in line (!16023).

  • Andreas fixed pointer arithmetic in the RTS linker’s flushInstructionCacheRISCV64 (!16419, #27569).

Build system

  • Sam made Hadrian check for cabal-install >= 3.12 upfront (!16132, #27317), rather than failing obscurely later on.

  • David fixed the ghc-internal .def file name (!16190), removed unused wrapper scripts from the Windows bindist (!16138), and made Hadrian avoid response files when the command line is short enough (!16134), as response files were impeding developer workflows (#27230).

  • David stopped ghc-toolchain throwing an exception when candidate executables are not found (!16173, #27369).

Testsuite

  • Sam made the test driver normalise call-stack line numbers when referring to locations in libraries (!16247, #27387), so that tests are no longer sensitive to irrelevant internal changes.

  • Andreas made the process009 test use SIGKILL (!16429).

  • Zubin made various improvements to the JUnit output, most importantly showing diffs in the GitLab summary (!16309) and reporting fragile failures as skipped (!16250). He also landed assorted testsuite fixes (!16413).

CI and infrastructure

  • Magnus worked on keeping nightly CI passing (!16296, #27127), adding a retry when fetching test metrics (!16281).

  • David made the lint-changelog job check for the no-changelog label in the script rather than in rules (!16177), which avoids having to re-run the entire pipeline when applying the no-changelog label.

  • Zubin arranged for tool messages to be reported as errors or warnings depending on the tool’s exit code, rather than always as errors (!16170, #27370).

process library

  • Zubin fixed link errors on certain macOS configurations by allowing posix_spawn_file_actions_addchdir to be missing when linking against process on Darwin (#377, #376).

Cabal

Releases

Recompilation checking

  • Sam stopped Cabal from writing setup-config twice (#11949), fixing access-denied failures (#11619).

  • Sam made cabal-install fall back to the external setup method on a Cabal-library mismatch (#11950), fixing stuck rebuilds of build-type: Custom packages (#11942).

  • Sam allowed preserving the local build artifacts across minor Cabal version bumps without causing recompilation or errors (#12289).

  • Tobias switched pre-processor recompilation checks to use file monitoring (#12021, with a preparatory refactoring in #12065). This fixes an issue with build tools not being re-run when their version changes (#11411).

Haskell Language Server

  • Andrea added whole-project loading (#5002), as described in his recent blog post. This builds on the groundwork Andrea laid in hie-bios: new load modes for upfront loading of a cradle or project (#508) and the componentsToLoad field (#515), both reviewed and merged by Hannes.

  • Hannes and Zubin pushed Guibou’s module-to-filename resolution over the finish line and applied further optimisations to put HLS’s import resolution on par with GHC’s (#4600).

  • Zubin made HLS unload linkables when any transitive dependency changes (#5035), and stopped HLS unloading all bytecode whenever new bytecode is generated (#5033).

  • Hannes set the FileCache hook before typechecking (#5030), fixing #4675.

  • Hannes ensured the DocMap is never computed with stale data (#4936).

  • Hannes tracked down multi-component session failures when expanding response files (#5004), fixed by whole-project loading.

  • Hannes substantially improved HLS’s error messages (#5029).

Google Summer of Code projects

Haskell syntax highlighting

  • Hannes transferred the VS Code syntax highlighting extension to the Haskell community (#256), fixing a mishap that had caused the extension to disappear from the VS Code marketplace, breaking syntax highlighting for many users.

Runtime observability

Haskell Debugger

Rodrigo continued to lead development of the Haskell Debugger (hdb), an interactive step-through debugger for Haskell, with contributions from Andrea and Hannes. It also gained a logo, designed by George Thomas (#326).

  • Hannes and Rodrigo added support for the future release of GHC 10.2 (#332, #359).

  • hdb has two mechanisms for listing threads, decoding stacks and collecting exception information: external compiler commands where GHC supports them, and a fallback that inspects the heap directly on older GHCs. Rodrigo separated the two into distinct modules selected by a Cabal version conditional, rather than interleaving them (#356).

  • Rodrigo made the singleThread flag of a continue request optional, as the Debug Adapter Protocol specifies (#38).

  • Hannes made the stack frame decoding logic use the source locations that StackAnnotation carries from ghc-internal-9.1402 onwards (#333).

  • Andrea made each stack frame report the variables bound in its own scope (#355, #160).

Live monitoring

Wen continued to develop eventlog-live, which allows GHC’s eventlog to be monitored as a program runs, streaming telemetry data from the runtime system to an external observability platform. One focus was on improving the OpenTelemetry integration.

Releases 0.6.0.0 through 0.9.0.0 came out this quarter. See the eventlog-live changelog for more details.

Stack and IPE profiling

Hannes and Wen worked on packages supporting stack profiling functionality, with a release of ghc-stack-profiler 0.4.0.0 (changelog) and ghc-stack-annotations 0.2.0.0 (changelog).

Wen rewrote ipedb’s LSM-tree database API (#18) and released 0.2.0.0/0.2.0.1 with other improvements (see the changelog).

]]> Well-Typed at ZuriHac 2026 https://well-typed.com/blog/2026/09/zurihac-well-typed-2026 hannes, adam community ghc open-source talks training tutorial youtube zurihac http://www.well-typed.com/blog/2026/09/zurihac-well-typed-2026 Thu, 10 Sep 2026 00:00:00 GMT Well-Typed was strongly represented at this year’s ZuriHac, with our team of Haskell experts giving six talks across ZuriHac itself and the Haskell Ecosystem and Implementors’ Workshops. If you couldn’t make it to ZuriHac, the recordings are now available. In addition, we are delighted that Dominik will be giving a keynote talk at MuniHac 2026 on 11th October, and there’s still time to register for MuniHac!

ZuriHac Advanced Track

Andres and Andrea hosted the Advanced Track at ZuriHac, delivering two one-hour presentations on implementing dependently typed languages in Haskell, with a focus on dependent pattern matching. They provide a good introduction to the world of dependent types as well as an in-depth discussion for language implementors.

Haskell Ecosystem Workshop

Andreas gave an excellent talk on how to contribute to the Haskell ecosystem and why companies in particular should want to do so.

Haskell Implementors Workshop

The Haskell Implementors Workshop was a great opportunity to share our progress on improvements to GHC over the last year. It’s always nice to take a moment to reflect on the progress we’ve made and the work we’ve done.

Andreas kicked things off with the annual GHC status report. This report provides a summary of the essential maintenance and community stewardship work that Well-Typed performs for the GHC project.

Next, Hannes introduced a prototype implementation of ghc-stack-profiler, a lightweight profiler that allows you to profile your application without compiling with -prof. The profiler uses source locations from -finfo-table-map for human readable profiles and can be used with GHC 9.10 and onwards. Expect an in-depth post about ghc-stack-profiler soon! You can also read more about our work in this area in posts tagged with profiling.

Finally, Rodrigo presented his progress on the haskell-debugger, a standalone step-through debugger for GHC. Since last year’s first introduction, many new features have been implemented, such as support for backtraces with source locations, custom debug visualisations of values and using the external interpreter for debugging multi-threaded applications.

Conclusion

Well-Typed offer Haskell Ecosystem Support Packages in partnership with the Haskell Foundation, to provide commercial users with support from Well-Typed’s experts, while investing in the Haskell community and its technical ecosystem. These projects were made possible by funding from our clients, notably Mercury, who are improving the experience for Haskell developers by supporting foundational work on Haskell tools.

It was great to meet everyone who attended the workshops and asked interesting questions during and after the talks. We hope to see you all again at MuniHac, or at next year’s ZuriHac!

]]> Whole project loading for Haskell IDE tooling https://well-typed.com/blog/2026/09/whole-project-loading-for-haskell-ide-tooling andrea well-typed hls open-source coding build-systems http://www.well-typed.com/blog/2026/09/whole-project-loading-for-haskell-ide-tooling Fri, 04 Sep 2026 00:00:00 GMT From Haskell Language Server 2.15.0.0 onwards, users can opt-in to loading all components of their current project up front, rather than as needed. Doing so ensures information about every module is fully available from the start, and avoids pauses to re-initialize the session when opening a file from a new component.

The feature is enabled by setting componentsLoading to "multi: whole-project" in the HLS configuration.

The next release of Haskell Debugger will load all components up front too. Debug sessions will then be able to support breakpoints from any module in the project, not just the entry point’s component.

The feature is provided by hie-bios >= 0.20 and the cradle config (hie.yaml) can be used to fine-tune the list of components to load. The new componentsToLoad field lets you list the exact targets to pick, which are otherwise the components listed in the cradle or inferred from the cabal/stack project.

Multi component sessions

Haskell Language Server has supported multi component sessions for a while, e.g. when working on a Cabal package with both a library and an executable their files can all be loaded together, so jumping to definition from app/Main.hs can land you in lib/Foo.hs.

However, so far each new component has been loaded into the session lazily, i.e. only when files belonging to the component are opened. There are caches involved, but each time this happens the GHC session is re-initialized from scratch: the new set of components, and how to build them, is discovered by querying the underlying build system, e.g. by invoking cabal repl/stack repl and extracting the flags they would pass to ghci. Ultimately the new component might have to go from being pre-compiled on disk to interpreted in-memory, forcing all its descendants to be reconfigured too, so even if we wanted to be more clever not much work could be saved.

This is not a big deal with just two components, but in a larger project it can be surprising to have HLS behave differently in a given file according to which other files have been opened. Also, when the session needs to be re-initialized because of a new component, the induced pause can be a bit jarring.

Whole project loading

The new whole project mode instead loads all project components right away, so that everything is available from the start. The downside is doing everything up front means memory use and initialization time are also paid up front. Also, a misconfigured component can stop the others from loading.

In Haskell Language Server

Eventually we hope to make whole project loading the default. For the moment, starting with haskell-language-server-2.15, the new feature is enabled by setting the new config field componentsLoading to multi: whole-project. The other options are multi: needed-only, which is the default, and single, which loads only a single component at once. The componentsLoading field replaces the previous sessionLoading one which is now deprecated: sessionLoading: "multipleComponents" is now componentsLoading: "multi: needed-only" and interpreted as such.

In Haskell Debugger

Haskell Debugger was actually the primary motivation for this work, as finding out in the middle of a debug session that you cannot add a breakpoint in an imported module is more dire than the issues with HLS.

Prior to whole-project loading, the typical setup where a package contains both a library and an executable that depends on it would end up with only the modules from the executable interpreted and so available to be stopped at. The library was installed in a temporary package database and included only as a dependency, so trying to set a breakpoint in a module from the library would just fail.

Haskell Debugger builds its session only once, as soon as it learns what the entry point is, i.e. the module and function to start execution from. At this point the debugger doesn’t know where the breakpoints will be, and so which modules need to be interpreted. As new breakpoints can be set while execution already started, waiting to know all of them to initialize the session is not an option.

Because of the above we have gone ahead and made whole-project loading the default and only way Haskell Debugger behaves, starting from the next release.

How it works and further configuration

What “all project components” means depends on the underlying cradle, either specified in a hie.yaml file or inferred from what can be found in the root directory. Recent enough Cabal and Stack are the two kinds of cradles that actually support this: if the hie.yaml file specifies components we load those, otherwise we ask the package manager to infer them. Inferring means asking Cabal for target all while enabling tests and benchmarks, or asking Stack for its default targets.

The above logic, like most of this new feature, is implemented by hie-bios starting from version 0.20. All details on how to fine-tune your cradle can be found in hie-bios’s README, including the new componentsToLoad field.

Before explaining the new field let’s go through a few examples with Cabal cradles to make things more concrete. For each case we will list the cabal repl invocation that hie-bios uses to fetch the correct flags.

A very minimal cradle (hie.yaml) will let cabal infer the components by using the target all, i.e.

cradle:
  cabal:

will result in cabal repl --enable-multi-repl --enable-tests --enable-benchmarks all. The --enable-* flags are included so that the session will cover everything in the project.

The --enable-* flags will override what specified in a cabal.project file, so if the cradle includes one we omit them, i.e.

cradle:
  cabal:
    cabalProject: "./cabal.project"

will result in cabal repl --enable-multi-repl --project-file=./cabal.project all.

If components are specified then those are the targets used, e.g.

cradle:
  cabal:
    components:
      - {"path": "./src", "component": "lib:foo"}
      - {"path": "./app", "component": "exe:foo"}

will result in cabal repl --enable-multi-repl lib:foo exe:foo.

Finally, if some component doesn’t play nice with cabal repl or the tooling that uses hie-bios, the field componentsToLoad can be used to specify the exact list of targets to use, for example

cradle:
  cabal:
    componentsToLoad: ["lib:foo","lib:bar"]

will result in cabal repl --enable-multi-repl lib:foo lib:bar.

Conclusion

Hopefully whole-project loading will provide a less surprising and smoother dev experience on projects with multiple components. It’s been my new default and working well for me since it got merged. Feedback is welcome on the HLS issue tracker. Issue #5005 is the issue about the feature introduction.

This work has been performed in collaboration with Mercury, who have a long-term commitment to the scalability and robustness of the Haskell ecosystem. Well-Typed are always interested in projects and looking for funding to improve HLS and other Haskell tools. Please contact info@well-typed.com if we might be able to work with you!

]]> New falsify release https://well-typed.com/blog/2026/07/falsify-4 edsko coding open-source testing http://www.well-typed.com/blog/2026/07/falsify-4 Fri, 17 Jul 2026 00:00:00 GMT Recently Martijn Bastiaan, QBayLogic’s COO, invited Well-Typed to come to QBayLogic HQ and give a one-day workshop on falsify, the new property based testing library that I developed for the Haskell Symposium back in 2023 (paper, presentation). QBayLogic is the company behind Clash: a purely functional language for hardware design. In case you haven’t heard of it, Clash translates Haskell to VHDL or Verilog, which can in turn be translated to actual hardware. It literally uses ghc as its frontend so you have essentially the full power of Haskell available. It’s a great project, I recommend checking it out.

The falsify library takes its main inspiration from the Python Hypothesis library, though it is not a direct translation: it takes the same core idea (“parse, don’t generate”) but reinterprets it in a way that better suits the Haskell way of thinking: more axiomatic approach, support for generating infinite data types (including functions), etc. For more information on falsify, see also the original blog post that announced it, falsify: Hypothesis-inspired shrinking for Haskell.

At QBayLogic HQ we spent the morning developing mini-falsify from scratch, so that we could focus on the main ideas without getting bogged down in the details of the full library; similar in spirit to for example TinyServant, or perhaps Stephen Diehl’s Typechecker Zoo. In the afternoon we hacked on falsify and its application within the clash ecosystem. Partly as a result of that work and partly as a result of me taking this opportunity to do some long overdue maintenance on falsify, there is now a new falsify release: falsify-0.4.0. In the remainder of this blog post we give a brief overview of the main changes.

New feature: Context

Most of this falsify release is just cleanup, but there is one important new feature, spear-headed by Peter Lebbing and Martijn Bastiaan from QBayLogic. The Property monad now has an important new function, called getContext:

getContext :: Property Context

The most important information that the context of a property provides is how many tests we are running for each property (how hard are we trying to falsify this property), and which iteration this particular attempt is.

This can be quite useful, for example when you want to start by looking at small test cases and then slowly broaden the scope. Just as a trivial example, consider the property that “no number is equal to 5”. If we use prim to generate the number to test, producing an arbitrary Word64, the chances that we will find the one counter-example (5) in that enormous search space are essentially non-existent:

demo :: Property ()
demo = do
    x <- gen Gen.prim
    assert $ P.ne .$ ("forbidden", 5)
                  .$ ("x", x :: Word64)

However, we could start with a small range and slowly grow that range; falsify now also offers a convenience function, defined in terms of getContext, for this specific purpose: sized, so-named because it is somewhat similar in spirit to sized in QuickCheck:

sized :: forall e a. (ProperFraction -> a) -> Property a

A ProperFraction is in the half-open interval [0,1); that is, between 0 (inclusive) and 1 (exclusive). We can use this to refine our demo property:

demo2b :: Property ()
demo2b = do
    l <- sized $ ProperFraction.scaleIntegral 100
    x <- gen $ Gen.inRange $ Range.inclusive (0, l)
    assert $ P.ne .$ ("forbidden", 5)
                  .$ ("x", x :: Word64)

This property is easily falsified.

As an aside, I would be somewhat cautious in using this approach. While it is sometimes unavoidable, in general I would recommend generating test case of arbitrary size and then shrinking them down; this is often more likely to actually find counter-examples. If there are specific edge cases that you want to hit, write a generator that covers those edge cases specifically, and perhaps use labelling (label and co) to check that those edge cases are indeed covered. However, as this demo shows, for some properties explicitly searching for small domains first can be very helpful.

Cleanup

The most important change in this release is a cleanup of the code base:

  • There is now a separate tasty-falsify package that provides integration with the tasty test framework; falsify itself now provides Test.Falsify.Driver.
  • The module hierarchy has been significantly cleaned up. For example, there are now a bunch of new Data.Falsify.* modules for specific datatypes; previously some of these were exported by Test.Falsify.Gen instead; now that module only contains the generators for those datatypes.
  • Deprecated functions have been removed
  • Some functions have been renamed and some type aliases have been replaced by newtype definitions for increased API clarity.
  • All Haddock warnings have been addressed.

For a full list of changes, please refer to the changelog.

Conclusions

Shrinking can be handled manually, in the style of QuickCheck; or automatically, in the style of hedgehog or in the style of falsify. If you are willing to put effort into writing good shrinkers for all your types, then QuickCheck is still your best bet.

If you consider the cost of manually writing shrinkers too large, then within the Haskell ecosystem you have a choice between hedgehog and falsify. The former has the considerable advantage that it’s been around for quite a long time and is a very polished library. The downside is that every time you use monadic bind you introduce a cut-point, which can often result in poor quality shrinking. With Hypothesis showing the way, falsify solves that cut-point problem, though even with falsify it still matters how you write your generators: shrinking is never truly free. Moreover, falsify should be considered an experimental library: it’s nowhere near as battle-tested as Hedgehog, never mind QuickCheck. That said, thanks to the interest of QBayLogic falsify is now a little more mature, so thank you QBayLogic!

For clients who are looking for professional support for the use of falsify, or indeed any other Haskell library, don’t hesitate to contact us at info@well-typed.com.

]]> Haskell ecosystem activities report: March–May 2026 https://well-typed.com/blog/2026/06/haskell-ecosystem-report-march-may-2026 adam, andrea, andreask, davide, duncan, hannes, magnus, mikolaj, rodrigo, sam, tobias, wen, wolfgang, zubin well-typed ghc community haskell-ecosystem-report http://www.well-typed.com/blog/2026/06/haskell-ecosystem-report-march-may-2026 Fri, 19 Jun 2026 00:00:00 GMT This is the thirty-first edition of our Haskell ecosystem activities report, which describes the work Well-Typed are doing on GHC, Cabal, HLS and other parts of the core Haskell toolchain. The current edition covers roughly the months of March 2026 to May 2026.

You can find the previous editions collected under the haskell-ecosystem-report tag.

Sponsorship

We offer Haskell Ecosystem Support Packages to provide commercial users with support from Well-Typed’s experts while investing in the Haskell community and its technical ecosystem including through the work described in this report. To find out more, read our announcement of these packages in partnership with the Haskell Foundation. We need funding to continue this essential maintenance work!

Many thanks to our Haskell Ecosystem Supporters: Standard Chartered, Channable and QBayLogic, as well as to our other clients who also contribute to making this work possible: Anduril, Juspay and Mercury; and to the HLS Open Collective for supporting HLS release management.

Highlights

Reinstallable base

Rodrigo and Wolfgang have continued working to disentangle base from GHC, with the ultimate goal of being able to use different versions of base with a single GHC version. This is all part of a long-term project to make GHC upgrades easier, documented in the reinstallable-base repo, and recently described in an excellent haskell.org blog article by Simon Peyton Jones. Simon, Rodrigo and Wolfgang are working together to rethink GHC’s treatment of “known-key names” so base will be much less tightly coupled to ghc-internal (!15899).

One big milestone was making the current base buildable both with GHC 9.14 (!16070) and with the upcoming GHC 10.0 (!16035).

Various other pieces of technical groundwork were required:

  • moving most of the System.IO implementation into base (!15694),
  • similarly moving Text.Read (!15693, !15777),
  • making various SafeHaskell-related changes (CLC #408, !16034).

Wolfgang also opened several CLC proposals identifying key areas that require further work:

  • the deprecation of unstable base modules (CLC #392), and
  • working towards making bytestring and text not depend on internal I/O machinery (CLC #410).

Semaphores and -jsem

The implementation of semaphores used by cabal-install and GHC to coordinate concurrency suffered from a serious issue when GHC and cabal-install were linked against different libc implementations (#25087).

Zubin remedied this issue with a new semaphore implementation on top of Unix domain sockets (!8), described in GHC proposal #673. GHC (!15729) and cabal-install (#11628) were then switched to this new protocol version.

As part of this work, Zubin also identified some deficiencies in the semantics of interruptible FFI (#27110).

Cabal modernisation

Sam worked to modernise the architecture of cabal-install by making it directly call the Cabal library to build packages (#11703). This unlocked the performance optimisations described in a recent blog post (#11767, #11768), achieving speed-ups of around 10-15% in certain situations.

In the long term, we would like to move towards Cabal having a fine-grained build graph across the whole project, rather than using a component-level build graph and relying on GHC to orchestrate the compilation of all the modules in a component/package. This will unlock more parallelism and other developer experience improvements.

Sam also implemented many improvements to build-type: Hooks, the modern replacement for build-type: Custom:

  • an improved API for SetupHooks authors (#11772),
  • better documentation (#11771),
  • improved recompilation checking for pre-build rules (#11731),
  • support for generating non-Haskell files in pre-build rules (#11573).

Tobias chimed in by adding support for recursive globs in file monitoring, which is useful for SetupHooks (#11658).

Windows DLL support

Duncan, with the help of David, embarked on the project of adding proper dynamic linking support to GHC on Windows. While this is still work-in-progress, several important steps have already been taken:

  • extending Cmm syntax to support symbols from external DSOs/DLLs (!15135),
  • solving the recursive DLL dependency between the RTS and ghc-internal (!15907),
  • making GHC use __attribute__((dllimport)) for external symbol declarations (!15914),
  • updating Hadrian to create individual .def files per ghc-internal DLL (!16082).

Critical process issue on macOS

Magnus diagnosed a critical issue with process on macOS (#27144, #356), implementing a fix in #363. As part of this work, he discovered an issue with several uploaded versions of process (#365) which was resolved by coordinating with the process maintainers.

GHC

Releases

Keeping all of GHC’s active release branches in good shape is a demanding, largely behind-the-scenes effort. Each release requires triaging and backporting a steady stream of bugfixes, with patches that often don’t cleanly apply and require careful reworking. Information about upcoming releases is available on the GHC release status page.

GHC currently has four (!) active branches. Zubin worked towards the 10.0 release as well as on 9.14.2; Magnus prepared 9.12.5, and Andreas took on 9.10.4.

Frontend

  • Rodrigo bumped the default language edition to GHC2024 (#26039, !14420). Starting from GHC 10.0, code without an explicit language edition will default to GHC2024. Compared to GHC2021, this adds the extensions DataKinds, DerivingStrategies, DisambiguateRecordFields, ExplicitNamespaces, GADTs, MonoLocalBinds, LambdaCase and RoleAnnotations.

  • Magnus fixed the documentation of getSizeofMutableByteArray# (!16065).

  • Sam fixed a loop with -XDeepSubsumption on GHC 9.14 (#26823, !15604).

  • Wolfgang made several performance improvements to the driver, allowing downsweep to use existing module graph nodes (!16028), introducing a cache for hole modules (!15888), and storing home unit dependencies as sets (!15849).

  • Hannes made several performance improvements to ghc-pkg, speeding up its closure computation (!16062) and migrating it to use OsPath (!15584).

  • Andreas modularised the GHC.Driver.Main module (!15940), as that single module had become quite unwieldy.

  • Following on from previous work allowing typechecker plugins to run in the pattern match checker (!14797), Sam made sure that plugins are only initialised once per module (!15485), fixing the regression reported in #26839.

  • Rodrigo provided a standalone reproducer for the simplifier slowness reported in #26989, which allowed Simon Peyton Jones to diagnose and fix this quadratic behaviour (!15725).

  • Sam investigated the type family performance regressions reported in #26426, identifying two key patches that had accidentally fixed the regression and recording these findings in Notes (!16113).

  • Andreas identified that a patch to use Generics within GHC significantly regressed compile times (#27191). The offending patch was reverted for the time being, and the coding style Wiki page was updated to document this unfortunate limitation.

Backend

  • Sam finished up work by Matthew Craven to improve the representation of floating point literals in GHC, fixing several issues with the treatment of negative zero and NaN values (!15528). This brings GHC much closer to proper IEEE 754 floating point compliance.

  • Andreas discovered a bug with AArch64 profiled dynamic builds of GHC and concluded that it was a bug in gcc/binutils (#26994).

  • Sam fixed a crash in Core Prep caused by invalid profiling tick occurrences (#27182, !16003).

  • Sam investigated a crash in mkDupableContWithDmds, and worked with Simon Peyton Jones to land a fix (#27261, !16084).

  • Sam fixed several bugs in the implementation of the hsExprType function (#26910, !15772).

  • Zubin fixed the typing of void pointer chains in capi FFI calls to avoid -Wincompatible-pointer-type errors by the C compiler (#26852, !15547).

  • Sam helped first-time contributor Avery Parker land his AmeriHac contribution to add constant folding for SIMD vector operations (!15512).

  • Sam reviewed several patches to the AArch64 native code generator by Ian Duncan, in the process uncovering a cluster of latent correctness bugs:

    • !15620 fixed a bug in “shift right” using a logical shift instead of an arithmetic shift (#26979). A separate register clobbering bug was identified and fixed.
    • !15619 fixed sign extension at 32-bit width (#26978). A separate bug with the overflow bit was identified and fixed (#27047). Another register clobbering bug was found and fixed separately (#27046, !16031).

  • Sam fixed a recalcitrant “failed to detect OverLit” crash in coreExprToPmLit (!15895, #27124, #25926).

  • Magnus and Sam investigated the GHC panic reported in #27227, which was narrowed down to Cabal bug #7684, and subsequently fixed (#11791).

ghci & bytecode

Work continued on making the bytecode interpreter, which underpins GHCi as well as the debugger, more capable and memory efficient.

  • Hannes introduced the -fimport-loaded-target ghci flag to fix a regression with the :add command relating to support for multiple home units (!15533, #26866).

  • Hannes fixed a regression in the behaviour of :load (#27202, !15980).

  • Hannes added support for hpc in the bytecode interpreter (#27036, !15843).

  • Rodrigo added support for static constructors in the bytecode interpreter, also fixing its treatment of unlifted values (#25636, !15221).

  • Hannes improved the memory usage of the bytecode interpreter by recording only a LinkableUsage instead of Linkable in LoaderState (#26500, #27018, !15689).

RTS

  • Duncan consolidated the ticker implementations to a single one on POSIX (!15781), removing signal-based ticker implementations (!15757, !16014) which presented a number of disadvantages (described in #27073).

  • David resurrected an old MR improving the documentation of the allocator (!3812).

  • Andreas added missing profiling headers for origin_thunk frames (!15665).

  • Duncan identified some incorrect STOP_THREAD status codes in ghc-events (#130).

Build system

  • David made several improvements to GHC’s build system and Hadrian, in relation to his work on Windows DLL support:

    • a fix for Unix paths in ACLOCAL_PATH (!16112),
    • proper LLVM program versioning logic (!16025),
    • work on response files to avoid MAX_PATH issues on Windows (!15891, !16120).

  • Andreas fixed an issue with --target in the configure script (!15649).

  • Zubin stopped Hadrian from including package hashes in Haddock directory names, as this was causing many broken links when browsing Haddocks (#26635, !15475).

GHC contribution experience

  • Magnus overhauled the MR template to be more helpful for new contributors (!15943, #27165).

  • Many team members provided reviews and helped land contributions from others, as described elsewhere in this report.

CI and tests

  • Magnus has been doing significant work on the gitlab.haskell.org instance and CI infrastructure to improve robustness of CI, deal with spam and manage the server load imposed by AI crawlers.

  • Magnus changed the Darwin CI to clone rather than copy when creating the Cabal cache (!15683).

  • Sam added a vendored mini-QuickCheck component for use in GHC’s testsuite, fixing some bugs in the previous implementation used in the foundation primops testsuite (!15893, #25969, #25990).

Haskell Language Server

  • Zubin prepared release 2.14.0 of the Haskell Language Server (#4897).

  • Hannes reviewed many HLS PRs from contributors:

    • #4958 adding a code action to delete unused bindings,
    • #4913 improving the handling of hs-boot files,
    • #4915 updating the splice plugin,
    • #4917 preserving qualified field names when expanding record inlay hints,
    • #4902 excluding internal superclass names in class placeholders,
    • #4886 cancelling outstanding threads when closing the SQLite connection,
    • #4867 improving HLS’s response for prepareRename,
    • #4865 migrating the Stackage build to use GitHub actions,
    • #4854 fixing a redundant hash in the ghcide cache path.

  • Hannes released version 0.19.0 of hie-bios (#506).

  • Sam fixed a hie-bios regression in which the local build directory would get overwritten, leading to cache trashing (#501, #503).

Haskell syntax highlighting

Sam fixed a large number of bugs in the language-haskell VS Code syntax highlighting extension.

Haskell Debugger

Rodrigo continued to lead development of the Haskell Debugger (hdb), an interactive step-through debugger for Haskell, with contributions from Andrea and Hannes. Built on top of the bytecode interpreter, it implements the Debug Adapter Protocol, allowing debugging of Haskell programs directly in the editor. We:

  • added a new RTS message to GHC allowing a thread’s flags (TSO flags) to be set or unset (!15831, #27131), which is needed to safely implement features like pausing, or toggling step-out/step-in per thread;

  • arranged for hdb to run the debuggee directly in the terminal when using the external interpreter (#260);

  • added support for custom external interpreter commands to GHC (!15676), making use of them rather than parsing heap terms (#222);

  • fixed a bug where forcing a thunk would invalidate stack frames on all threads rather than just the right one (#292), and fixed breakpoints being overwritten by looking for active breaks in the correct ModBreaks (#298);

  • refactored the home-unit session initialisation (#279).

Andrea made various quality-of-life improvements to the debugger:

  • allowing imports at the REPL (#229);
  • bringing interactive imports back into scope after resuming execution (#275);
  • inheriting the entry file’s language extensions (#230);
  • adding LogMessage support to implement log points (#223);
  • sharing a single HDB+GHC session for use with HLS (#308).

Runtime observability

ghc-debug

Hannes performed various maintenance tasks on ghc-debug, a key tool for out-of-process heap analysis of Haskell programs:

  • released version 0.8.0.0 (!88),
  • bumped version bounds (!91),
  • fixed FreeBSD support (!89),
  • landed an old MR by Teo Camarasu, adding support for the non-moving GC (!10).

eventlog-live, eventlog-socket

Wen continued to develop eventlog-live, which allows GHC’s eventlog to be monitored live as a program runs. Highlights of the changes to eventlog-live:

  • support for receiving eventlog input over TCP (#154, #155),

  • improved profiling support with cost-centre profiles (#134) and ghc-stack-profiler profiles (#131),

  • integration with the RTS control server (#139, #122, #126),

  • a new demo showing eventlog-live monitoring GHC itself (#138, #148),

  • support for GHC 9.12 (#136).

This also included a litany of improvements to the underlying eventlog-socket library:

  • lifecycle hooks (#63),
  • command registration (#45),
  • support for startProfTimer and stopProfTimer (#65),
  • allow building with hsc2hs in cross-compilation mode (#64).

Finally, Wen also landed several supporting changes in GHC itself:

  • fixed a race condition in the RTS between flushEventLog and starting/stopping event logging (!15750),
  • added a new -lI eventlog flag to emit IPE events (!16004),
  • added support for dynamically changing trace flags (!15936).

ghc-stack-profiler

Hannes continued maintaining ghc-stack-profiler, a profiler that relies on stack annotations rather than heavier profiling mechanisms:

  • released version 0.2.0.0 (#24);

  • made the profiler more robust, ensuring it never crashes on decoding errors (#12) and backporting a fix for stack-decoding segmentation faults from GHC HEAD (#20);

  • integrated the profiler with eventlog-socket, adding support for its lifecycle hooks (#19) and an eventlog-socket test suite (#25);

  • improved thread management by using async (#10) and exposing stopStackProfilerThread (#11).

IHaskell

Sam added Windows support to IHaskell, a library that provides Haskell integration for Jupyter notebooks (#1595).

stm library

Magnus performed some important maintenance tasks on the stm library, adding missing compiler versions to CI (#98) and fixing a slow test (#97).

]]> Faster Cabal Haskell builds by eliminating redundant work https://well-typed.com/blog/2026/05/faster-haskell-builds sam build-systems cabal community compile-time-performance open-source sovereign-tech-fund http://www.well-typed.com/blog/2026/05/faster-haskell-builds Thu, 28 May 2026 00:00:00 GMT TL;DR Build your Haskell projects 10-15% faster with this one simple trick! (Spoiler: the simple trick is to wait for the next major cabal-install release.)

In previous work (paid for by the Sovereign Tech Fund) we did a lot of heavy lifting to make a major architectural change to Cabal. That work is now paying off with practical benefits. This post covers follow-on architectural improvements to cabal-install which then enable us to eliminate redundant work in the configure phase, yielding significant reductions in build times.

The changes will be available to everyone in the next major cabal-install release. For a large project like pandoc (including all of its dependencies) we measure a 10% (std.dev. 0.6pp) reduction in wall clock time for a 16-way parallel build with --semaphore. No user changes are needed to take advantage of this improvement.

History: Cabal and cabal-install

The genesis: the Cabal specification

First, there was Cabal. Its design was laid out in A Common Architecture for Building Applications and Tools. Fundamentally, it defines the notion of a package, with each package being built and installed with the following sequence of commands:

> hc Setup.hs
> ./Setup configure
> ./Setup build
> ./Setup install

Each package must be built in dependency order, with hc-pkg registering each installed library into a package database.

Orchestrating the build of multiple packages

cabal-install was then born to plan and execute a build plan consisting of many packages. With its solver, it determines a build plan, which is then orchestrated by running the above sequence of commands for each package, in dependency order.

There is however one architectural mismatch: for the solver to be able to compute a build plan, it already needs a lot of information about the current system:

  • What Haskell compiler are we using?
  • What system libraries are available (pkgconfig-depends)?
  • What build tools are available (build-tool-depends)?

This means that cabal-install already has in its hands most of the information necessary for configuring a package; in particular it has already resolved all the conditionals in every package description. We should thus be able to skip most of the steps in the package’s ./Setup configure phase. However, the command-line interface of ./Setup configure makes it practically impossible to do so: passing a fully resolved dependency graph would require many additions to the already bloated ConfigFlags datatype, and a lot more data being serialised/deserialised.

Because of this limitation, cabal-install’s approach was to take its hard-won build plan and convert it into ConfigFlags that specify exact dependency versions and flag assignments. This amounts to passing ./Setup configure an already fully constrained configuration; the configure step would then re-probe the system, re-read package databases… only to re-discover exactly what cabal-install already knew!

A new architecture for cabal-install

The paradigm shift proposed in our Sovereign Tech Fund proposal is that cabal-install should be responsible for orchestrating the whole build process instead of running the conceptually independent build systems provided by each package. With cabal-install now in control, it can directly call Cabal library functions, which in turn allows skipping steps in the configure phase that waste time re-discovering information that cabal-install is already aware of.

To implement such a change, we first needed to prepare the terrain: when invoking an external executable such as the Setup executable – say via the process library as Cabal uses – we can set the working directory, environment variables and redirect input/output handles. It was not possible to do this directly via the Cabal library, so we first needed to add Cabal library support for setting the working directory and for choosing logging handles. Once this was done, it allowed us to refactor cabal-install to directly call Cabal library functions to build packages.

Performance impact

This architectural change provides a solid foundation for further improvements. The two main time sinks in the Cabal configure phase were determined to be (using a new --build-timings flag to cabal-install):

  1. (~50% of configure time) Re-configuring the compiler program database. The compiler and hc-pkg were already pre-configured, but other programs such as haddock, ar, ld etc were re-configured anew for each package.
  2. (~40% of configure time) Re-probing the installed package database, via hc-pkg dump.

We can skip this extra work by pre-configuring the compiler ProgramDb and keeping a running InstalledPackageIndex. These two changes, taken together, reduce the time spent in the configure phase by over 90%.

While most of the time in builds is unsurprisingly spent… actually compiling Haskell code [citation needed], the impact on full builds is still rather significant. For example, when compiling aeson with -j1, we saw a reduction in total build time of ~16.6% (std.dev. 1.9pp) in our benchmarks.

The fact that the configure phase is inherently serial also means that these improvements have a notable impact when combined with the -jsem feature. This is because the -jsem feature allows us to assign more capabilities to the build phase. As per Amdahl’s law, this results in the configure phase becoming more of a bottleneck. For example, when compiling pandoc with cabal install pandoc -j16 --semaphore, we saw a reduction in total build time of ~10% (std.dev. 0.6pp).

Further improvements

These improvements provide a small glimpse of what is possible after our changes to cabal-install’s architecture. A more ambitious long-term goal would be for cabal-install to manage a “giant build graph” on a finer granularity level than whole Cabal components. For example, if package q depends only on module P1 from package p, we could imagine starting to compile q after compiling P1 but before we have finished compiling the rest of p. This would unlock build-time reductions by increasing available parallelism, and also enable more accurate progress and error reporting.

]]> Exception Annotations: Lay of the Land https://well-typed.com/blog/2026/05/lay-annotation-land edsko coding exceptions http://www.well-typed.com/blog/2026/05/lay-annotation-land Fri, 08 May 2026 00:00:00 GMT Exception annotations were introduced in GHC 9.10, and can be an invaluable tool for debugging thorny problems. The initial implementation had some important limitations that made them less useful in practice than one might hope, but fortunately the situation has since been much improved. In this blog post we will give a detailed overview of the status quo as of GHC 9.12/9.14, identify some gotchas you should be aware and provide advise on how to deal with them, and briefly look ahead to what will change in GHC 10.0. We will also dedicate a section to discussing the problems in GHC 9.10, for those who cannot yet upgrade.

Although we will recap all necessary definitions, this blog is not meant to be an introduction to exception annotations; if you have never used them before, you might first want to watch The Haskell Unfolder Episode 29: exceptions, annotations and backtraces.

Backtraces

Before we look at the general framework for exception annotations, let’s first briefly recap the concept of backtraces, which is GHC’s answer to stack traces in other languages. The situation is more complicated in Haskell due laziness, and there are actually four different kinds of backtraces:

  • based on HasCallStack annotations
  • based on cost-centres (which will require compiling your program with profiling enabled)
  • based on IPE info
  • based on DWARF info

In this blog post we will use the first two only, but for the purposes of our main discussion here the choice actually does not matter much; see GHC proposal Decorate exceptions with backtrace information for details. If you’re interested in IPE backtraces specifically, you might also be interested in our blog post Better Haskell stack traces via user annotations, which discusses some recent extensions we implemented to improve these.

HasCallStack backtraces

Consider this simple Haskell program, where main calls top calls middle calls bottom:

bottom :: HasCallStack => IO ()
bottom = do
    bt <- collectBacktraces
    putStrLn $ displayBacktraces bt

middle :: HasCallStack => IO ()
middle = bottom

top :: HasCallStack => IO ()
top = middle

main :: IO ()
main = top

A HasCallStack is essentially an additional function argument which is automatically populated by GHC at call sites with information about where the function was called. When we run this program, we see something like this:

HasCallStack backtrace:
  collectBacktraces, called at exe/DemoCallStack.hs:13:11 in (..)
  bottom, called at exe/DemoCallStack.hs:18:10 in (..)
  middle, called at exe/DemoCallStack.hs:22:7 in (..)
  top, called at exe/DemoCallStack.hs:25:8 in (..)

The only thing worth noting here is that the moment a HasCallStack chain is broken, the backtrace is cut off there. For example, if middle does not have a HasCallStack constraint, we can no longer see where middle was called from:

HasCallStack backtrace:
  collectBacktraces, called at exe/DemoCallStack.hs:19:11 in (..)
  bottom, called at exe/DemoCallStack.hs:24:10 in (..)

The fact that top still has a HasCallStack constraint does not matter: the callstack is cut at the first missing link.

Cost centre backtraces

Cost centres are how GHC implements profiling: very roughly, the cost of a computation is attributed to its enclosing cost centre (see chapter Profiling of the GHC manual). Like HasCallStack, this relies on source code annotations:

{-# SCC bottom #-}
bottom :: HasCallStack => IO ()
bottom = do
    bt <- collectBacktraces
    putStrLn $ displayBacktraces bt

{-# SCC middle #-}
middle :: IO ()
middle = bottom

{-# SCC top #-}
top :: HasCallStack => IO ()
top = middle

{-# SCC main #-}
main :: IO ()
main = do
    setBacktraceMechanismState CostCentreBacktrace True
    top

Unlike HasCallStack, however, GHC offers ways for inserting such annotations automatically, which can often make cost centre based callstacks more practical than HasCallStack. The most common flag to do this is -fprof-auto or (in recent GHC) -fprof-late (see Late Cost Centre Profiling). This inserts cost centres around all top-level functions, as we did manually above.

Cost centre backtraces must be explicitly enabled by calling setBacktraceMechanismState, and you need to compile your code with profiling enabled; the cabal option --enable-profiling both enables profiling as well as automatic cost centre insertion. The backtrace for this example might look something like

Cost-centre stack backtrace:
  DemoCallStack.main (exe/DemoCallStack.hs:(32,1)-(34,7))
  DemoCallStack.top (exe/DemoCallStack.hs:28:1-12)
  DemoCallStack.middle (exe/DemoCallStack.hs:24:1-15)
  DemoCallStack.bottom (exe/DemoCallStack.hs:(18,1)-(20,35))

Be aware however that optimizations can delete cost centres, especially in simple examples like this (#27225).

Cost centres vs exception handling

Consider the following example: as before, main calls top calls middle calls bottom, which prints a backtrace; however bottom then throws an excepton. Meanwhile, main installs an exception handler called handlerTop, which in turn calls handlerMiddle calls handlerBottom, which prints its own backtrace:

bottom :: HasCallStack => IO ()
bottom = do
    bt <- collectBacktraces
    putStrLn $ displayBacktraces bt
    throwIO $ userError "Uhoh"

middle :: HasCallStack => IO ()
middle = bottom

top :: HasCallStack => IO ()
top = middle

handlerBottom :: HasCallStack => SomeException -> IO ()
handlerBottom _e = do
    bt <- collectBacktraces
    putStrLn $ displayBacktraces bt

handlerMiddle :: HasCallStack => SomeException -> IO ()
handlerMiddle e = handlerBottom e

handlerTop :: HasCallStack => SomeException -> IO ()
handlerTop e = handlerMiddle e

main :: IO ()
main = do
    setBacktraceMechanismState CostCentreBacktrace True
    top  `catch` handlerTop

The HasCallStack backtrace printed by bottom is

HasCallStack backtrace:
  collectBacktraces, called at exe/DemoCCS.hs:24:11 in (..)
  bottom, called at exe/DemoCCS.hs:29:10 in (..)
  middle, called at exe/DemoCCS.hs:32:7 in (..)
  top, called at exe/DemoCCS.hs:41:5 in (..)

as before; the HasCallStack printed by handlerBottom is very similar:

HasCallStack backtrace:
  collectBacktraces, called at exe/DemoCCS.hs:13:11 in (..)
  handlerBottom, called at exe/DemoCCS.hs:17:19 in (..)
  handlerMiddle, called at exe/DemoCCS.hs:20:16 in (..)
  handlerTop, called at exe/DemoCCS.hs:41:18 in (..)

For the cost-centre based backtrace, the one shown in bottom is as before:

Cost-centre stack backtrace:
  DemoCCS.main (exe/DemoCCS.hs:(39,1)-(41,27))
  DemoCCS.top (exe/DemoCCS.hs:32:1-12)
  DemoCCS.middle (exe/DemoCCS.hs:29:1-15)
  DemoCCS.bottom (exe/DemoCCS.hs:(23,1)-(26,30))

but the one shown in handlerBottom is more surprising:

Cost-centre stack backtrace:
  DemoCCS.main (exe/DemoCCS.hs:(39,1)-(41,27))
  DemoCCS.top (exe/DemoCCS.hs:32:1-12)
  DemoCCS.middle (exe/DemoCCS.hs:29:1-15)
  DemoCCS.bottom (exe/DemoCCS.hs:(23,1)-(26,30))
  DemoCCS.handlerTop (exe/DemoCCS.hs:20:1-30)
  DemoCCS.handlerMiddle (exe/DemoCCS.hs:17:1-33)
  DemoCCS.handlerBottom (exe/DemoCCS.hs:(12,1)-(14,35))

Whether or not this is expected/correct behaviour is arguable, but the rule is this: the cost centre stack is not restored until we leave the scope of catch. Put another way: the cost centre stack reflects the fact that bottom “calls” handlerTop, however indirectly. This applies transitively: if handlerTop would throw an exception, which would then be caught by some other exception handler, then its backtrace would reflect that top “called” handlerTop “called” that other exception handler. This kind of situation can arise quite naturally, for example when using handlers that deallocate some resources and then rethrow the exception.

Basic definitions

Before we look at the subtleties that arise from actually catching and throwing (or rethrowing) exceptions, we’ll first get the basic definitions out of the way. These have not changed much between recent GHC versions and are hopefully uncontroversial.

Exception annotations

Exceptions annotations can basically be anything at all; the only requirement is that that we can display them:

class Typeable a => ExceptionAnnotation a where
  displayExceptionAnnotation :: a -> String

An important instance of this class is Backtraces, which wraps a set of different kinds of backtraces:

instance ExceptionAnnotation Backtraces where
    displayExceptionAnnotation = Base.displayBacktraces

Exception context

An exception context is essentially just a list of exception annotations. However, since those annotations may be of different types, we need to wrap them in an existential:

data ExceptionContext = ExceptionContext [SomeExceptionAnnotation]
data SomeExceptionAnnotation = forall a. ExceptionAnnotation a => SomeExceptionAnnotation a

There are functions for manipulating the exception context. The most important are emptyExceptionContext and addExceptionAnnotation, for creating an empty context and inserting an annotation into an existing context respectively.

emptyExceptionContext  :: ExceptionContext
addExceptionAnnotation :: ExceptionAnnotation a => a -> ExceptionContext -> ExceptionContext

Pivotal change: SomeException

The pivotal change in all of this is in the definition of SomeException which, starting in GHC 9.10, now has an associated list of annotations:

data SomeException = forall e. (Exception e, HasExceptionContext) => SomeException e
type HasExceptionContext = (?exceptionContext :: ExceptionContext)

The use of an implicit parameter means that pattern matching on SomeException remains possible in the same way as before (though the annotations would be silently dropped).

There are various functions for extracting and manipulating the exception context associated with an exception, such as someExceptionContext and addExceptionContext:

someExceptionContext :: SomeException -> ExceptionContext
addExceptionContext  :: ExceptionAnnotation a => a -> SomeException -> SomeException

However, probably the most important function for extending exception contexts is annotateIO, which installs an exception handler that extends any exception that is thrown with the specified annotation:

annotateIO :: forall e a. ExceptionAnnotation e => e -> IO a -> IO a
annotateIO ann (IO io) = IO (PrimOp.catch# io handler)
  where
    handler se = PrimOp.raiseIO# (addExceptionContext ann se)

It is important to emphasize that this is implemented with primops, not with the regular catch and throwIO functions, which do considerably more than merely catching and throwing, as we shall see.

Exception type class

The Exception type class is a central abstraction in Haskell’s exception ecosystem. As part of the exception annotation work, it has received one minor extension, and it was changed in two not-so-minor-but-rather-subtle ways. Let’s first get the part out of the way which has not changed: exceptions are no good if we cannot see them:

class (Typeable e, Show e) => Exception e where
  displayException :: e -> String
  displayException = show

  -- (..)

backtraceDesired

The minor extension is a new function called backtraceDesired, which indicates if a backtrace should be attached to exceptions of this type; we will see how this function is used when we discuss the implementation of throwIO.

class (Typeable e, Show e) => Exception e where
  -- (..)

  backtraceDesired :: e -> Bool
  backtraceDesired _ = True

The argument to backtraceDesired is already fully constructed exception; the question is whether a backtrace should be added to that exception. In most cases the argument can simply be ignored, but it doesn’t have to be. For all but a handful of specialized cases the default implementation (indicating that yes, we want a backtrace) will be fine.

fromException

The not-so-minor-but-rather-subtle changes are in fromException and toException, which remove and add the SomeException wrapper around exceptions respectively. Let’s first look at fromException:

class (Typeable e, Show e) => Exception e where
  -- (..)

  fromException :: SomeException -> Maybe e
  fromException (SomeException e) = cast e

This may look no different from the implementation prior to 9.10, but recall that SomeException now has an additional field: the exception annotations. As mentioned above, a pattern match like this will silently discard those annotations.

toException

The final function in the Exception class is toException, which is intended to add the SomeException wrapper.

class (Typeable e, Show e) => Exception e where
  -- (..)
  toException :: e -> SomeException

Prior to 9.10, the default implementation literally just added the SomeException constructor:

  -- implementation prior to 9.10
  toException = SomeException

However, starting in 9.10 we also need to give an initial value for the exception context. The default implementation, reasonably enough, chooses the empty context:

  -- implementation in 9.10, 9.12, 9.14, and 10.0
  toException e = let ?exceptionContext = emptyExceptionContext in SomeException e

Unfortunately, however, the documentation of toException has also been modified, and now states that toException should produce a SomeException with no attached ExceptionContext. Personally, I think that is a mistake (#27194); we will discuss this in the next session.

⚠️ Caution: Instance for SomeException itself

SomeException itself is also an instance of Exception; fromException is trivial, and backtraceDesired and displayException piggy-back on the definition of whatever exception is wrapped:

instance Exception SomeException where
  fromException = Just

  backtraceDesired (SomeException e) = backtraceDesired e
  displayException (SomeException e) = displayException e

  -- (..)

The definition of toException is more problematic, however. Prior to 9.10, calling toException on SomeException was just an identity:

instance Exception SomeException where
  -- (..)

  -- Prior to 9.10
  toException se = se

Now, however, the implementation must clear the existing context in order to satisfy the contract:

instance Exception SomeException where
  -- (..)

  toException (SomeException e) = let ?exceptionContext = emptyExceptionContext in SomeException e

I think this is simply wrong; at the very least, it is highly counter-intuitive, and it also does not match the original proposal; I don’t know why this was changed. We will see some consequences of this design choice when we discuss throwing exceptions.

Newtype helpers

There are two auxiliary types, with their own Exception instances, that can be helpful when throwing or catching exceptions in specific ways. We haven’t discussed either throwing or catching yet, but we will nonetheless discuss these auxiliary types first as we will need them in the subsequent sessions.

NoBacktrace

NoBacktrace can be used to override backtraceDesired:

newtype NoBacktrace e = NoBacktrace e

instance Exception e => Exception (NoBacktrace e) where
  fromException = fmap NoBacktrace . fromException
  toException (NoBacktrace e) = toException e
  backtraceDesired _ = False
  -- displayException left at its default implementation

ExceptionWithContext

The other, arguably more imporant, auxiliary type is ExceptionWithContext. The definition itself is straight-forward: it simply pairs some value with an exception context:

data ExceptionWithContext a = ExceptionWithContext ExceptionContext a

The idea is that this type gives us a way to catch exceptions of specific types (rather than catching SomeException), and still get access to the exception context. For example:

data MyException = MyException
  deriving stock (Show)
  deriving anyclass (Exception)

example :: IO ()
example = someAction `catch` \(ExceptionWithContext ctxt MyException) -> do
    -- (..)

The implementation is reasonably straight-forward:

instance Exception a => Exception (ExceptionWithContext a) where
    toException (ExceptionWithContext ctxt e) =
        case toException e of
          SomeException c ->
            let ?exceptionContext = ctxt
            in SomeException c

    fromException se = do
        e <- fromException se
        return (ExceptionWithContext (someExceptionContext se) e)

    backtraceDesired (ExceptionWithContext _ e) = backtraceDesired e
    displayException = displayException . toException

That said, the devil is very much in the detail with these kinds of definitions, and as we shall see, it was defined incorrectly in GHC 9.10.

Throw

The primary function for throwing an exception is throwIO, which is defined as1

throwIO :: (HasCallStack, Exception e) => e -> IO a
throwIO e = do
    se <- toExceptionWithBacktrace e
    IO (PrimOp.raiseIO# se)

Most of the actual work happens in toExceptionWithBacktrace:

toExceptionWithBacktrace :: (HasCallStack, Exception e) => e -> IO SomeException
toExceptionWithBacktrace e =
    if backtraceDesired e then do
      bt <- Base.collectBacktraces
      return (addExceptionContext bt (toException e))
    else
      return (toException e)

That is, if a backtrace is desired, we collect one and add it as an annotation to the exception that we’re about to throw.

Generalization

In GHC 9.14 toExceptionWithBacktrace was generalized to

toExceptionWithBacktrace :: (HasCallStack, Exception e) => e -> IO SomeException
toExceptionWithBacktrace e =
    if backtraceDesired e then do
      SomeExceptionAnnotation ea <- collectExceptionAnnotation
      return (addExceptionContext ea (toException e))
    else
      return (toException e)

This is an experimental API (not yet part of base); see CLC #348 for details. The idea is that you can use setCollectExceptionAnnotation to register your own function to be run to construct an annotation whenever an exception is thrown anywhere. For example, if you’re worried that some IO faults are happening due to your CPU overheating, you might use

newtype Temperature = Temperature Int
  deriving stock (Show)
  deriving anyclass (ExceptionAnnotation)

getTempCPU :: IO Temperature
getTempCPU = -- (..)

main :: IO ()
main = do
    setCollectExceptionAnnotation getTempCPU
    -- (..)

By default, the collection callback is collectBacktraces, so unless you register a different callback the behaviour is the same as in 9.10 and 9.12.

⚠️ Caution: Throwing SomeException

Because throwIO calls toException, and since toException for SomeException clears the exception context, you probably don’t want to call throwIO on an argument of type SomeException: any exception annotations that might be embedded in that exception will be lost.

The most common case for throwing SomeException is inside an exception handler; we will cover this specific case of rethrowing exceptions when we discuss onException, but we can reuse the same combinators also to define a general “throw precisely this exception” function:

raiseIO :: SomeException -> IO ()
raiseIO (SomeException e) = rethrowIO (ExceptionWithContext ?exceptionContext e)

Catch

The most important change in GHC 9.12 from 9.10 is in the definition of catch, which now implements the WhileHandling proposal. The idea is that when we throw a new exception while handling another, we annotate that new exception with the old exception: the new exception arose while handling the old exception:

data WhileHandling = WhileHandling SomeException deriving Show

catch :: Exception e => IO a -> (e -> IO a) -> IO a
catch (IO io) handler = IO $ PrimOp.catch# io handler'
  where
    handler' se =
      case fromException se of
        Just e' -> PrimOp.catch# (unIO (handler e')) (handler'' se)
        Nothing -> PrimOp.raiseIO# se

    handler'' se se' = PrimOp.raiseIO# (addExceptionContext (WhileHandling se) se')

⚠️ Caution: Rethrowing the same exception

An important combinator for dealing with exceptions is onException, which runs some specified action when an exception occurs (typically some resource cleanup) and then rethrows the exception again:

onException :: IO a -> IO b -> IO a
onException io what = io `catch` \e -> do
    _ <- what
    throwIO (e :: SomeException)

As written, this is suboptimal: for every layer of onException, we re-throw the annotation stripped from its original annotations (due to throwIO and toException for SomeException), and with a new WhileHandling annotation with the original exception (due to catch). This result in unnecessary noise: all the information is still there, but it’s buried. When we rethrow the same exception, there is no need for WhileHanding: we should just throw the original exception as-is.

To solve this, base now offers new functions specifically to catch-and-rethrow: catchNoPropagate2 is like the old catch, without the handler that adds the WhileHandling annotation; and rethrowIO, which avoids adding a backtrace (using NoBacktrace; moreover, both of these explicitly preserve contexts (using ExceptionWithContext):

catchNoPropagate :: Exception e => IO a -> (ExceptionWithContext e -> IO a) -> IO a
catchNoPropagate (IO io) handler = IO $ PrimOp.catch# io handler'
  where
    handler' se =
      case fromException se of
        Just e' -> unIO (handler e')
        Nothing -> PrimOp.raiseIO# se

rethrowIO :: Exception e => ExceptionWithContext e -> IO a
rethrowIO e = throwIO (NoBacktrace e)

This then enables the following improved implementation of onException:

onException :: IO a -> IO b -> IO a
onException io what = io `catchNoPropagate` \e -> do
    _ <- what
    rethrowIO (e :: ExceptionWithContext SomeException)

⚠️ Caution: Displaying exceptions

The final pitfall we need to discuss is displaying exceptions. Usually we call displayException to do so, but this does not show annotations. The idea is that displayException is meant to render an exception for users, not necessarily developers.3 Starting withGHC 9.14 there is a separate function displayExceptionWithInfo, but that is not available in GHC 9.12; moreover, even in GHC 9.14 I would advise against using it when you are debugging, as it only shows the top-level annotations, making things like WhileHandling much less useful.

Personally, I like to use my own custom exception handler which shows the full exception, and makes a few other improvements also: it makes the nesting structure clearer, and reorders annotations to improve readability; you can find an example implementation on GitHub .

GHC 9.10

If you cannot upgrade from GHC 9.10, unfortunately the exception annotation infrastructure has some important limitations. Upgrade if you can; if not, this section will explain what you need to be aware of.

Lost annotations

As we remarked when we discussed catch, the WhileHandling proposal only got implemented in GHC 9.12. In GHC 9.10 the definition of catch was still unchanged from its definition before the exception annotation proposal:

catch :: Exception e => IO a -> (e -> IO a) -> IO a
catch (IO io) handler = IO $ PrimOp.catch# io handler'
  where
    handler' se =
      case fromException se of
        Just e' -> unIO (handler e')
        Nothing -> PrimOp.raiseIO# se

However, the Exception instance for SomeException was already changed, so that toException clears the exception context. This means that if an exception with annotations is ever caught and rethrown anywhere, in a pattern such as

someAction `catch` \(e :: SomeException) -> throwIO e

those annotations will be lost. Similarly, since onException had not yet been changed either, any call to onException, and by implificationbracket, anywhere in your callstack would also lose any annotations:

bracket :: IO a -> (a -> IO b) -> (a -> IO c) -> IO c
bracket before after thing =
    mask $ \restore -> do
      a <- before
      r <- restore (thing a) `onException` after a
      _ <- after a
      return r

onException :: IO a -> IO b -> IO a
onException io what = io `catch` \e -> do
    _ <- what
    throwIO (e :: SomeException)

In both cases, throwIO will insert a new backtrace, but that backtrace will point to where the exception was rethrown, not to where it was thrown originally. What’s worse, neither bracket nor onException have a HasCallStack constraint, so all we see in the callstack is the call to throwIO from onException itself.

Cost centre stacks do help a bit here (provided you enable profiling): at least you’ll get to see the full backtrace to the exception handler, and with a bit of luck even to the original call to throw, due to the semantics of semantics of cost centres in exception handlers. That won’t always be the case though (for example, in the case of asynchronous exceptions), and you won’t see any of the additional annotations that might have been added to the exception.

Duplicated annotations

The Exception instance for ExceptionWithContext in GHC 9.10 has an incorrect definition for toException:

instance Exception a => Exception (ExceptionWithContext a) where
  -- (..)

  -- implementation in GHC 9.10
  toException (ExceptionWithContext ctxt e) =
      let ?exceptionContext = ctxt in SomeException e

(We saw the correct definition above.)

This is wrong for two reasons:

  1. It does not use toException of the underlying type (the a type parameter); in most cases this does not matter, because toException rarely does anything interesting. Even in the case of SomeException, where toException does something “interesting” (if perhaps ill-advised), to wit clear the exception context, that doesn’t matter here because we are overriding that context anyway. However, there might be types where toException genuinely does something important (even if I am not aware of any such cases currently).
  2. In the specific case that a is SomeException, this will create a nested SomeException: SomeException (SomeException someOtherException) with two copies of the context (the annotations).

The second point here is more important: if we later have exception handlers that manipulate the exception context, they will manipulate the outer context but not the inner. Indeed, if that “manipulation” is “clear the context” (see previous section), we might end up in the somewhat bizarre situation where these two problems cancel out: if we have

someAction `catch` \(ExceptionWithContext ctxt (e :: SomeException))
  throwIO $ ExceptionWithContext ctxt e

then this exception handler will duplicate the annotations, a later exception handler might lose the outermost annotations (previous section) but not the inner, and all of a sudden annotations that were lost mysteriously re-appear; see GHC ticket #27194.

Unfortunately, this is not a viable workaround for the lost annotation problem, as it changes the type of the exception nested in the (outer) SomeException from whatever it really should have been to (the inner) SomeException, which will break any exception handlers for that specific type.

GHC 10.0

The upcoming GHC 10.0 releases makes a few improvements to the exception annotation infrastructure. The first important improvement is that exception handling in STM was lagging behind a bit; this will be rectified (#25365).

The other important fix is in onException. Consider again the definition we saw when we discussed rethrowing exceptions:

onException :: IO a -> IO b -> IO a
onException io what = io `catchNoPropagate` \e -> do
    _ <- what
    rethrowIO (e :: ExceptionWithContext SomeException)

We mentioned that that catchNoPropagate does not install an exception handler that installs a WhileHandling annotation, because we are rethrowing the very same exception. However, if what throws an exception that is no longer the case! The definition of onException is therefore modified to

onException io what = io `catchNoPropagate` \e -> do
    _ <- annotateIO (whileHandling e) what
    rethrowIO (e :: ExceptionWithContext SomeException)

See CLC Proposal #397 for details. As an example, consider what happens if the release callback of bracket itself throws an exception:

data ReleaseFailed = ReleaseFailed
  deriving stock (Show)
  deriving anyclass (Exception)

bottom :: HasCallStack => IO ()
bottom = annotateIO (MyAnnotation 123456789) $ throwIO MyException

middle :: HasCallStack => IO ()
middle = bracket (return ()) (\() -> throwIO ReleaseFailed) $ \() -> bottom

top :: HasCallStack => IO ()
top = middle

With the new definition onException (and my custom exception display function, which is still needed), we get

demo-bracket-release-fail: Uncaught exception of type ReleaseFailed
  ReleaseFailed
  HasCallStack backtrace:
    throwIO, called at exe/DemoBracketReleaseFail.hs:42:38 in (..)
    middle, called at exe/DemoBracketReleaseFail.hs:46:7 in (..)
    top, called at exe/DemoBracketReleaseFail.hs:55:5 in (..)
  WhileHandling
    MyException
      MyException
      MyAnnotation 123456789
      HasCallStack backtrace:
        throwIO, called at exe/DemoBracketReleaseFail.hs:38:48 in (..)
        bottom, called at exe/DemoBracketReleaseFail.hs:42:70 in (..)
        middle, called at exe/DemoBracketReleaseFail.hs:46:7 in (..)
        top, called at exe/DemoBracketReleaseFail.hs:55:5 in (..)

Very nice!

Conclusions

Exception annotations can be invaluable when debugging difficult problems. While the initial implementation in GHC 9.10 had some important limitations, the situation has since been much improved. Provided you use GHC 9.12 or later, there are two things to pay attention to in your own code (these apply to 9.12, 9.14 and 10.0):

  • Define your own custom function to display exceptions, which shows all annotations, not just the top-level ones (or use mine).
  • Be cautious with throwing SomeException: toException for SomeException will clear the exception context, which is almost certainly not what you want. For catch-and-rethrow, use the combinators available specifically for that purpose.

That said, there are still a few minor shortcomings to be aware of:

  • GHC 9.12 and 9.14:

    • Exception handling in STM has not yet been updated: throwSTM does not collect a backtrace, and catchSTM does not add any WhileHandling annotations (#25365).
    • onException does not add any WhileHandling exceptions; as a result, if the resource deallocation callback to bracket itself throws an exception, the original exception will be lost.

    Both of these will be addressed in GHC 10.0.

  • exceptions-0.10.9: this is the version of exceptions that is bundled with GHC 9.12, but lags behind a bit. For example, the definition of generalBracket in exceptions-0.10.9 does not use any of the abstractions for rethrowing; this is fixed in exceptions-0.10.12. The impact is however limited: it merely means that there are some extraneous WhileHandling annotations, resulting in unnecessary noise.

  • Any catch-and-rethrow patterns implemented in other packages should not lose any annotations, provided that they use catch from base.

  1. We will ignore calls to withFrozenCallStack, which hide some internal functions from the HasCallStack backtrace. This makes the backtrace slightly more readable, but does not otherwise change anything. See CLC #387.↩︎

  2. Some versions of base distinguish between catchExceptionNoPropagate and catchNoPropagate, which differ only in some strictness annotations. Strictness can make a big difference, especially when IO actions are undefined rather than throwing an exception. However, this is its own can of worms, and outside the scope of this blog post. See CLC proposal #383 for some discussion.↩︎

  3. In GHC 9.10, displayException did show annotaitons, but this got rolled back in 9.12; see CLC #285 for a detailed discussion.↩︎

]]>