Informal Codes

Announcing template-haskell-lift and template-haskell-quasiquoter

2025-10-04T00:00:00+00:00

The template-haskell</code> package has a large interface, which includes both stable and unstable parts. The unstable part changes with almost every new version of GHC. This introduces extra work for users of the library who only rely on the stable parts. They now have to update their upper bounds to accommodate the new major version in order to use a new version of GHC.</p>

I’m happy to announce the first release of two libraries that expose stable subsets of the template-haskell</code> interface:</p>


template-haskell-lift</code>: a stable home for the Lift</code> typeclasss.</li>

template-haskell-quasiquoter</code>: a stable home for the QuasiQuoter</code> type.</li>
</ul>

These implement GHC Proposal 696</a>.</p>
By replacing a dependency on template-haskell</code> with one or both of these libraries,
users will be more insulated from breaking changes.</p>
These smaller interfaces are much less likely to change going forward.
If they do change, we will try to release versions that are compatible with multiple major versions of GHC to ease the transition.</p>
In some cases, these smaller libraries also allow us to backport new features to older versions of GHC.
For instance, GHC-9.16’s template-haskell</code> library will ship with a new defaultQuasiQuoter</code></a> utility,
but if you use template-haskell-quasiquoter</code> you will be able to benefit from this immediately.</p>
Using template-haskell-lift</code>🔗</a></h2>
Suppose you have a module that defines a datatype Foo</code> and you want to add a Lift</code> typeclass instance.</p>
You should add template-haskell-lift</code> to your .cabal</code> file’s build-depends</code> section and then you can derive a Lift</code> instance like so:</p>
{-# </span>LANGUAGE</span> DeriveLift #-}
</span>module </span>Foo
</span>import Language.Haskell.TH.Lift (</span>Lift</span>)
</span>
</span>data Foo = ...
</span>  deriving Lift
</span></code></pre>
If you need to write a custom instance, I would recommend using (Typed) Template Haskell splices, rather than using the TemplateHaskell AST types directly from template-haskell</code>.
template-haskell-lift</code> provides compatibility shims for lifting some types that lack appropriate Lift</code> instances.</p>
Using template-haskell-quasiquoter</code>🔗</a></h2>
Similarly for QuasiQuoter</code>s, users can add template-haskell-quasiquoter</code> to their build-depends</code> and then use it like so:</p>
module </span>FooQuasi
</span>import Foo
</span>import Language.Haskell.TH.QuasiQuoter (</span>QuasiQuoter</span>(..)</span>, </span>namedDefaultQuasiQuoter</span>)
</span>import Language.Haskell.TH.Lift (</span>lift</span>)
</span>
</span>fooQQ :: QuasiQuoter
</span>fooQQ = namedDefaultQuasiQuoter "fooQQ" {quoteExp = \str -> lift . read @Foo}
</span></code></pre>
Conclusion🔗</a></h2>
These libraries should help make it easier to upgrade to a new version of GHC.
The more people use them, the greater the benefits will be, so I encourage folks to start using them in their own libraries.</p>
For more information about plans to improve the stability of Template Haskell, take a look at my HEW 2025 talk</a>.
For more information about the design of these libraries take a look at GHC Proposal 696</a>.</p>
If you encounter any issues or have suggestions, please open an issue on the respective issue tracker:</p>

https://gitlab.haskell.org/ghc/template-haskell-lift/-/issues</a></li>
https://gitlab.haskell.org/ghc/template-haskell-quasiquoter/-/issues</a></li>
</ul>

Upgrading the CircuitHub codebase to GHC-9.10

2025-08-19T00:00:00+00:00

We have recently upgraded the CircuitHub codebase from GHC-9.8 to GHC-9.10. Overall it has been a pleasant upgrade experience. This is thanks to the effort that the entire ecosystem has been putting into stability lately, including but not limited to: the Haskell Foundation Stability working group, the GHC steering committee, GHC developers, the core libraries committee, and of course all the individual maintainers. This blog post will list some of the changes we had to make and is inspired by Tom Ellis’s experience report about upgrading from GHC-8.10 to GHC-9.6</a>.</p>

Updating upper-bounds 🔗</a></h2>
The vast majority of the required changes consisted of updating upper bounds on our dependencies. Many packages needed to update their bounds on boot libraries like `base</code> or template-haskell</code>. Often no actual changes were required to the library itself.</p>`
`New exports from Prelude</code>`🔗</a></h2> base-4.20</code> now exports foldl'</code> from Prelude</code>. This is a welcome change. It has been a footgun that other folds are exported from Prelude</code>, but the one you want most of the time wasn’t.</p> This change led to many redundant import warnings in our project. Like many production codebases, we disallow warnings, so we had to amend many of our modules’ imports to no longer import foldl'</code> from Data.Foldable</code> or Data.List</code>.</p> Changes like this make me wish for the ability to apply HLS code actions to an entire codebase. This would have been resolved by applying the “Remove redundant imports” action followed by a reformat.</p> Data.List.NonEmpty.unzip</code> warning🔗</a></h2> In base-4.20</code>, Data.List.NonEmpty.unzip</code> gained a new warning about future monomorphisation (See: CLC#86</a>). We ended up disabling this warning globally by adding -Wno-x-data-list-nonempty-unzip</code> to the ghc-options</code> in all of our cabal files.</p> We use cabal-fmt</code>’s fragment</code> pragmas, which allows us to share a snippet of code between .cabal</code> files. This allowed us to add this flag to a common stanza, and share it in all of our .cabal</code> files. So this wasn’t much work for us to accommodate.</p> DataKind</code> warnings🔗</a></h2> GHC-9.10 added some warnings to do with missing DataKind</code> pragmas. Rather than resolving these individually, we ended up just enabling the DataKind</code> extension globally in our all modules. This was made quite easy again by our use of a cabal-fmt</code> common fragment.</p> Addition of Data.Text.show</code>🔗</a></h2> text-2.1.2</code> exported a new Data.Text.show</code> identifier. Packages that didn’t import Data.Text</code> qualified had to be updated to avoid errors from using show</code>.</p> ghc-source-gen</code> breakage🔗</a></h2> The ghc-source-gen</code></a> lets you generate Haskell code by using GHC’s own ASTs. By depending on GHC’s AST, you are always guaranteed to be producing valid syntax. On the other hand, depending on GHC internals means that it breaks almost every release and requires significant amounts of CPP. The package was fixed by Ian-Woo Kim in this</a> PR.</p> Given that this package is likely to break in the future, the best approach might be to not depend on it if possible. For instance the popular proto-lens</code> library makes use of this, and if the maintainers are willing then it would be great if we could rewrite its Haskell generation to not use ghc-source-gen</code>. See proto-lens#512</code></a>.</p> It has also been identified in the Facundo Domínguez’s GHC API stability work</a>, and that might lead to some improvements.</p> HIE bug🔗</a></h2> When upgrading weeder</code> to use the new compiler, we discovered a bug</a> in its parsing of HIE files. Zubin Duggal investigated and it turned out to be a bug in weeder</code>’s usage of the HIE API rather than a bug in GHC.</p> Conclusion🔗</a></h2> This was a relatively easy GHC upgrade. Most of the changes were minor and just had to do with imports.</p> Before trying to upgrade to GHC-9.12, I will try to see if we can remove ghc-source-gen</code> from our dependency closure. Any package like this which is tightly coupled to the GHC API is likely to need updating after every release. Reducing one’s dependency footprint and removing fragile package is often a good way to make future upgrades easier.</p> From some cursory attempts to get GHC-9.12 working, it sounds like that upgrade will be even easier.</p>



HIW 2025 Talk: Catching space leaks at compile-time using th-deepstrict
2025-06-06T00:00:00+00:00
I gave a talk entitled Catching space leaks at compile-time using th-deepstrict</code></em> at the Haskell Implementors Workshop 2025.</p>
You can find the slides here</a> and watch the recording on YouTube here</a>.</p>


HEW 2025 Talk: Template Haskell as a Case Study in (In)stability
2025-06-05T00:00:00+00:00
I gave an invited talk entitled Template Haskell as a Case Study in (In)stability</em> at the Haskell Ecosystem Workshop 2025.</p>
You can find the slides here</a> and watch the recording on YouTube here</a>.</p>


Working towards a more stable Template Haskell
2024-05-06T00:00:00+00:00
Template Haskell enables writing programs that generate and manipulate Haskell code.
This is a powerful tool that lets us avoid boilerplate and expand the expressivity of the language.
Yet, its power comes with a risk. Users of Template Haskell often end up being tightly coupled to the template-haskell</code> support library.
This library defines Template Haskell’s version of the Haskell syntax tree and the interface between Template Haskell and GHC.
Almost every release of GHC leads to a breaking change to this library to reflect the ever expanding range of syntax accepted by GHC.
These changes often break user code. Over time libraries that use template-haskell</code> amass a bunch of conditionally compiled code to enable compatibility with
a wide range of template-haskell</code> versions.</p>
This post is about some work I have been doing with Sebastian Graf and other GHC devs to help avoid Template Haskell breaking user’s code in the future.
This is a well known problem (see GHC ticket #24021</a>).
There is no simple, single solution. Both the API and its patterns of usage are complex.</p>
So far, our focus has been on the internal relationship between GHC and the template-haskell</code> library. We managed to untie some knots that
tightly coupled together each version of GHC to their bundled version of template-haskell</code>, and knots that made it difficult to change the interface of template-haskell</code>.
With these blockers out of the way, it should be possible to make some changes to give us much stronger stability guarantees.</p>
Before embarking on implementing these exciting improvements, we wanted to share our plans to get feedback and to invite the community to collaborate with us.</p>
I’ll sketch how Template Haskell leads to instability, the changes we are planning to make, the changes we’ve made so far and how you can get involved.</p>
Why Template Haskell leads to broken code🔗</a></h2>
At the very core of the template-haskell</code> library is a set of data types that represent Haskell syntax trees: Expr</code>, Type</code>, Dec</code>, Pat</code>, etc.
These types often change, because they reflect the source-syntax of GHC Haskell, in its full glory. That in turn means that any code that directly uses these data types (for construction or pattern matching) will break as new releases of GHC change the source-syntax. We want to loosen this undesirable coupling between the source-syntax and user code.</p>
We can divide usages of Template Haskell by how they relate to these syntax tree types. At a high level, a specific usage either produces/constructs or consumes/deconstructs these types. We can further subdivide these into four categories:</p>

(A) Producing with quotes</li>
(B) Producing with constructors or smart constructors</li>
(C) Consuming through reification</li>
(D) Consuming for syntax analysis</li>
</ul>
A library that makes use of Template Haskell is likely to have a mixture of these usage patterns. For instance, a common case is a library that produces derived typeclass instances. Such a library might use reification (type C) to look up the definition of a data type, then use smart constructors (type B) to generate the definition of the instances themselves.</p>
Let’s now briefly look at each of these usage classes, and their bearing on user code stability.</p>
Producing syntax using constructors: unstable, but popular (type B)🔗</a></h3>
By far the most popular way to produce Template Haskell syntax trees is by either directly using constructors (VarE</code>), or by using the monadic smart constructors (varE</code>) exported by Language.Haskell.TH.Lib</code></a>. These both make users vulnerable to breakage when the syntax tree types change.</p>
For instance, in template-haskell-2.18</code>, the ConP</code> constructor, which represents a constructor pattern was given a new field to represent the possibility of a list of type applications preceding the argument. This led to the following code</a> in esqueleto</code> to break:</p>
pure </span>$ </span>ConP 'Value [VarP var]
</span></code></pre>
This then had to be patched to give an empty value for the new field (and conditional compilation had to be introduced to support both versions):</p>
pure </span>$ </span>ConP 'Value </span>[]</span> [VarP var]
</span></code></pre>
By using these constructors or smart constructors directly to produce syntax trees, users expose themselves to breakage whenever a new field is added. And as we’ve pointed out, these happen often.</p>
Producing syntax using Quotes: stable, but unpopular (type A)🔗</a></h3>
Template Haskell quotes produce syntax trees in a very stable manner. Haskell’s concrete syntax develops in a backwards compatible way. Changes to the language will not cause x + y</code> to stop being accepted, and neither will it break [| x + y |]</code>, irrespective of whether the representation of infix operations in the Template Haskell syntax tree types changes. By using quotes, we can piggy-back off these existing backwards compatibility guarantees.</p>
Returning to our example from before, we could have expressed the same thing using quote syntax as:</p>
[p|</span> Value $(varP var) </span>|]
</span></code></pre>
This wouldn’t have broken, and is unlikely to ever break with a newer version of template-haskell</code>.</p>
Yet, quotes are much less popular than direct uses of constructors. There are definitely some places where quotes (currently) fall short and we are trying to track these here</a>. These don’t completely explain their low uptake though. The example above shows one place where they could’ve been used to make code more stable, but weren’t.</p>
Next time you are writing Template Haskell code, try using quotes. If you run into issues let us know on the GHC bug tracker, whether they are to do with limitations in expressivity, error messages, or lack of documentation.</p>
Consuming syntax through reification (type C)🔗</a></h3>
template-haskell</code> exports a reify</code> family of methods to lookup information about identifiers.</p>
For instance:</p>
reifyType </span>:: Name -> Q Type
</span></code></pre>
Here reifyType</code> will return the type of the given identifier. But the notion of type in play is that of source-language type syntax, which is full of syntactic clutter like parentheses, infix operators, list and tuple notation, etc. For reification we don’t want source syntax; we want a nice small representation of the type (type variable, arrow, forall, type constructor application etc). This is simply a mis-design of Template Haskell’s reification interface.</p>
Not only does this get in the way when we want to analyse the results from reification functions, since we need to wade through the details of source-language syntax, but we are also exposed to breaking changes from when these types often change. Returning to the ConP</code> example, if we pattern matched on a ConP</code> constructor, our code would break when the new field was added.</p>
Consuming syntax for analysis (type D)🔗</a></h3>
Exhaustively pattern matching on Template Haskell syntax trees is the rarest usage pattern. Users might for instance want to find all free variables, or transform the entire syntax tree into a different representation.</p>
Such users are inherently tightly coupled to the exact definition of syntax trees for a given version of GHC. Because this case is both much more difficult and much more rare than the others, we currently aren’t focused on avoiding breaking changes here. Indeed it’s hard to see how that could be possible.</p>
How we can avoid tight coupling🔗</a></h2>
Now we move from the current situation to the ways we can improve it. In this section I will be summarising the Plan to Stabilise Template Haskell</a> document I’ve written up, which in turn is trying to synthesise the various ideas by GHC developers and others into a concrete plan.None of these plans are set in stone, and they could benefit from feedback and experimentation.</p>
The tight coupling we have sketched consists of two components: (i) the definitions of the syntax tree types changing regularly with new versions of GHC; (ii) user code depends on the exact definitions of the syntax tree types.
When these two elements combine, code breaks. So, our aim is to as much as possible reduce the prevalence of one (or both) of these.</p>
Loosening coupling between GHC and template-haskell</code>🔗</a></h3>
Of the usage patterns we’ve examined, only one, type D, cares about seeing the entire, exact syntax trees that correspond to GHC’s current version of the source-language. All of the other use cases can be satisfied with a mere subset of the language. This opens up a possibility that allows us to avoid breaking changes for the vast majority of users, without requiring any modifications to their usage of Template Haskell. The idea is to let a user use a version of template-haskell</code> whose syntax potentially corresponds to the source-language of an older GHC. In so doing, we can decouple releases of GHC and template-haskell</code>, and have it make breaking changes on its own schedule and implement migration plans.</p>
For instance, let’s again examine the ConP</code> breaking change. This came out in template-haskell-2.18</code> bundled with GHC-9.2</code>. But consider if we had released a minor version of template-haskell-2.17</code> that insulated against this change by exporting a pattern synonym that defaulted the new field always to []</code>, and ignored the field when pattern matching. Then users could have upgraded their GHC without even having to change the bound on their template-haskell</code> dependency and their code would have continued to compile.
This strategy wasn’t actually possible to implement at the time due to some blockers that we’ve only recently cleared.</p>
This sort of migration strategy would work for type A, B, and C clients, but cause issues for type D clients, who explicitly want the latest syntax tree. We would have to enable some way for them to access this without any compatibility shims, perhaps through a different template-haskell-unstable</code> package.</p>
This example is only one of the possibilities amongst many of how this migration could have been implemented. Another option would be to rename the constructor when adding the new field and keep the name ConP</code> for a compatibility pattern synonym that matches the old definition.</p>
How exactly we implement these should be decided on a case by case basis. The important detail is that by decoupling template-haskell</code> and GHC, we introduce slack into the relationship that makes these sorts of gradual migration plans possible.</p>
Any sudden ecosystem migration is a great burden on maintainers, and can be slow to fully implement. Therefore this strategy is very attractive because it requires no work for downstream maintainers. This complements greater usage of quotes well. Quotes still should probably be used for new Template Haskell code. But by implementing something like this, we avoid putting maintainers into a double bind where they either need to quickly rewrite their code into a different style or suffer from breaking changes. This would give time for the transition to happen more gradually.</p>
These compatibility shims could likely not be maintained indefinitely, so users would benefit from a sliding window of compatibility. They would still need to upgrade their template-haskell</code> package bounds eventually.</p>
This naturally leads to another strategy. We can also expose copies of the syntax tree types that correspond to some well-defined version of the language like Haskell2010</code>. If users move to depending on these interfaces then they can get even stronger stability guarantees. As we would have a moving window of support for GHC versions for each version of the template-haskell</code> interface, but we could support these well-defined versions almost indefinitely. The trade-off is that this would require modifications to downstream code, but still much less modification than rewriting one’s code to use quotes throughout.</p>
Loosening coupling between template-haskell</code> and user code🔗</a></h3>
We plan to improve the interface of Template Haskell, so that users aren’t forced into tight coupling.</p>
We are hoping to find the pain points and improve the experience of using Template Haskell quotes. Then users could benefit both from this nicer syntax and the stability benefits it would bring. For instance, we are looking at adding (untyped) pattern quotes</a> that would allow one to pattern match on Template Haskell syntax trees using quotes.</p>
We are planning to improve the experience of deconstructing syntax tree values by introducing named record fields. These would allow users to only look at the fields they care about and mean that their pattern matching code wouldn’t break when new fields are added. This would primarily help type D clients, but would also benefit type C clients who occasionally want to pattern match shallowly on Template Haskell syntax trees.</p>
To improve the experience when reify</code> and friends, we are planning to transition these methods to return types that return some sort of normalised types rather than the syntax tree types. These would be closer to GHC’s Core or System F rather than surface syntax. This is what users want anyway when performing analysis. For instance libraries like th-abstraction</code></a> and th-desugar</code></a> already implement forms of normalisation (to differing degrees), and express an appetite for this. We can draw on these libraries to guide our design.</p>
What’s happened so far🔗</a></h2>
My efforts so far have been focused on clearing roadblocks that have blocked changes like these in the past.
I have merged two MRs into GHC: !12306</a> and !12479</a>.
These have benefited greatly from reviews and collaboration from Sebastian Graf, Matthew Craven and others.
Collectively these two change the relationship between GHC and template-haskell</code>, so that it becomes a library just like any other.</p>
The first of these changes the way the bootstrapping of Template Haskell works.
Historically, the process required that the interface of the new template-haskell</code> library matched the interface of the template-haskell</code> library that came with the bootstrapping compiler in certain ways. This made it difficult to refactor template-haskell</code> (see #23536</a>). Small changes could lead to difficult to debug errors. We resolved this through a form of vendoring, allowing two versions of template-haskell</code> in essence to co-exist at the same time. Thus removing the requirement.</p>
The second change moves any identifiers that have a special wired-in status to the ghc-internal</code> package, mirroring the changes to base</code>.
This then meant that template-haskell</code> can become a completely normal package that just happens to be where certain wired-in identifiers are conventionally re-exported from.</p>
With these changes implemented, the ideas I sketched out in the previous are now much more easily achievable.</p>
How you can get involved🔗</a></h2>
This is a great stage to get involved. I would love to hear feedback on the plan I’ve sketched, and if you have time on the Plan to Stabilise Template Haskell</a> document.</p>
I would especially like to hear about concrete examples where Template Haskell quotes have been lacking to help guide us to improve this feature. We feel like Template Haskell quotes are vastly underutilised and would love to help remove barriers to people adopting them. We are trying to gather up issues here</a>.</p>
It would also be great to see more people get involved in this process, and maybe help prototype some of these ideas. You don’t have to be a confident GHC developer to take part!</p>
A few of us will be at ZuriHac 2024 where we will be working on improving Template Haskell. Come join us!
Sebastian has collated some tickets</a> about improving Template Haskell (not all stability related).</p>
The future is looking bright for Template Haskell. I’m really hoping that very soon we will be able to give strong guarantees to users that upgrading GHC won’t lead to any breakages caused by Template Haskell.</p>
Acknowledgments🔗</a></h2>
Thanks to Adam Gundry, Sebastian Graf, Simon Peyton Jones, and Michael Peyton Jones for reading and commenting on a draft of this post.</p>