This is basically a rehash of some setup notes I made while preparing a proposal for the Google Summer of Code 2025, based on the project idea proposed by Facundo Domínguez. More detailed information can be found at the LH documentation site and source repository.

LH is under active development, with a focus on quality-of-life features that make it a breeze to use (or maybe not quite yet, but its getting there). I believe that using refinement types to specify programs unlocks expressive possibilities, enabling stronger guarantees and clearer intent, that are worth exploring.

About Liquid Haskell

LH is a tool that allows programmers to enforce contracts on their functions inputs (pre-conditions) and outputs (post-conditions). This is done through special comment annotations that extend a function type signature with refinement types: types that include constraints defined by logical predicates.

A typical example is that of a “successor” function, which we can specify to take only positive integers and guarantee to produce only positive integers.

{-@ succ :: {v : Int | v > 0} -> {v : Int | v > 0 } @-}
succ :: Int -> Int
succ n = n + 1

We can be more succinct by declaring a refinement type alias.

{-@ type Pos = {v : Int | v > 0} @-}

{-@ succ :: Pos -> Pos @-}
succ :: Int -> Int
succ n = n + 1

Other arithmetic properties like “multiplication by a positive integer preserves order” can be specified as well.¹

{-@ type OrderedPair = { pair : (Int,Int) | fst pair < snd pair } @-}

{-@ escalarMultiplication :: Pos -> OrderedPair -> OrderedPair @-}
escalarMultiplication :: Int -> (Int,Int) -> (Int,Int)
escalarMultiplication n (x,y) = (n * x, n * y)

Note that we can use regular Haskell functions in the predicates, here fst and snd to access the components of the pair. These are available, along with other functions from the Haskell standard library (the “prelude”), because LH comes bundled with their specifications (defined using assumptions). In general, Haskell functions need to be lifted into the logic using reflect and other constructs (which I don’t cover here) to be used in specifications. LH verifies that given an ordered pair, we get back an ordered pair, so that our specification is correct. But also that this function is only called with ordered pairs, so that the specification is enforced at every call site. To accomplish this LH renders the specifications into a collection of constraints (think of a system of equations) that are passed to an external SMT solver that verifies the specification.

I think of this as an alternative (or perhaps, complimentary) approach to property based testing, in which properties are logically proven instead of being checked against (cleverly) random generated input. In practice, what this means is that we can express properties of our code and document its behaviour in place.

Installation

First, we’ll need the Haskell toolchain: cabal to manage the project and the ghc Haskell compiler. The (current) recommended way to install and manage both is through GHCup.² After installing it with the default options, install a ghc version that corresponds to a LH release (check the docs). In this tutorial we’ll use ghc-9.10.1 and liquidhaskell-0.9.10.1.2.³

ghcup install ghc 9.10.1

The following command bootstraps the creation of our project. It creates a new cabal project for our tutorial, with the corresponding base and liquidhaskell versions as dependencies, and configures it to use the corresponding version of ghc.

mkdir lh-tutorial && cd lh-tutorial && \
cabal init --lib --dependency="base==4.20.0.0,liquidhaskell==0.9.10.1.2"  && \
cabal configure --with-compiler ghc-9.10.1

LH is implemented as a GHC plugin, which modifies the compiler pipeline to deliver the extracted constrains to an SMT solver for verification. For it to work, you must have any of the following installed in your system and accessible from your $PATH environment variable: Z3, CVC4 or MathSat The LH docs recommend Z3, which should be available from your Linux distribution package manager. On MacOs, it can be installed using Homebrew: brew install z3.

To use LH, we need to indicate GHC to use the plugin. We can do so by modifying the library stanza of the lh-tutorial.cabal.

library
    import:           warnings
    exposed-modules:  MyLib
    -- other-modules:
    -- other-extensions:
    build-depends:
        base ==4.20.0.0,
        liquidhaskell ==0.9.10.1.2
    hs-source-dirs:   src
    default-language: Haskell2010
    ghc-options: -fplugin=LiquidHaskell -- ADD THIS LINE!

This enables LH verification across all modules in the project. Finally, build the project with cabal build. If the build succeeds, now LH has been properly installed within the project. For the time being, you should be notified that no constraints where checked.

Dummy Library

Modify the contents of src/MyLib.hs to include the examples from before.

module MyLib where

{-@ type Pos = {v : Int | v > 0} @-}

{-@ succ :: Pos -> Pos @-}
succ :: Int -> Int
succ n = n + 1

{-@ type OrderedPair = { pair : (Int,Int) | fst pair <= snd pair } @-}

{-@ escalarMultiplication :: Pos -> OrderedPair -> OrderedPair @-}
escalarMultiplication :: Int -> (Int,Int) -> (Int,Int)
escalarMultiplication n (x,y) = (n * x, n * y)

If you cabal build now, you’ll see that some constraints have actually been checked. Now you’re ready to work on your own project, using these steps as a template.

Using a local build of Liquid Haskell

Since I plan to work on the LH codebase and test my changes across various projects, I need a way to use my local build. We now examine a couple of approaches, broadly described here, to accomplish this.

We start by cloning LH source with the --recurse-submodules flag so that the liquid-fixpoint package is also cloned (needed for the build).

git clone --recurse-submodules https://github.com/ucsd-progsys/liquidhaskell.git

The upstream source is developed against the ghc version corresponding to its latest realease, so make sure to install it (at the time of writing its 9.12.2). The build instructions can be found at the source repository README, suggest using the following command:

cabal build liquidhaskell

This should build, but cabal is known to have its quirks. If it does, proceed to the next section. If it doesn’t, carefully check the installation documentation at the source repository and the documentation site. It is possible that your current cabal library version does not support the needed ghc version (check the error message), so you might need to change (set) it. Installation and set of different versions of Haskell tools can be done within ghcup tui. If the problem persists, consider rising an issue.

Symlink

The simplest way to use our build in a project is to create a symlink to our liquidhaskell local repository in our project.

ln -s /path/to/liquidhaskell/ /path/to/lh-tutorial/

For cabal build to pick it, we point to it in a cabal.project file within the lh-tutorial project.

echo "package: . liquidhaskell" > cabal.project

Local Repository

As an alternative, we can create a local package repository for cabal to fetch the dependency from instead of Hackage. The advantage of this approach is that we can easily use our build across projects.

First, build the liquidhaskell package tarball and place it in the directory intended for the local repository. You can do this by running this command at the source repository root.

cabal sdist -o /absolute/path/to/local/repository

Now declare a local no-index repository in the cabal configuration file (typically found at $HOME/.cabal/config or $HOME/.config/cabal/config) by adding this line:

repository local-repo
  url: file+noindex:///absolute/path/to/local/repository

We also need to set our local repository to have a higher priority than Hackage. This is done by editing the active-repositories field in the cabal config file, putting the local repository at the end of the list.

active-repositories: hackage.haskell.org, local-repo

Running cabal update makes cabal discover and merge our repository into its index. In this way, every local project having liquidhakell == 0.9.10.1.2 as a dependency will fetch our tarball build instead of Hackage’s. A downside of this approach is that we will need to erase the .cache file (that cabal puts in our local repository directory) whenever we update our build tarball.

Wrap Up

In this tutorial, we covered how to enable and use Liquid Haskell in a project, as well as how to apply your local build across multiple projects. This should give you everything needed to start building with LH or contribute to its source code. Now go break some (verified) code!

Tepoztlán

Tepoztlán is located about 70 kilometers south of Mexico City, in a valley of steep mountains (that seem to have been pushed out from the underground) and lush glens during rainy season. It is a town proud of its traditions with a remarkable cultural and religious syncretism. I’ve been living here for 7 years, and will continue for the foreseeable future.

We are currently facing environmental and social imbalance caused by a complex real state black market, that neglects the National Park status and regulations, and annual fires that threaten the ecosystem. In this context, nurturing community is critical to counteract the dismantling of the social fabric. This is no easy task, as the social spheres seem to orbit different stars at times. Before this workshop, I gave a talk at the central church about algorithms and live coding practice. So this is a second effort towards sharing both my artistic and research interests with my local community, as most of my activities are usually online or in Mexico City.

Assistants and venue

Four people came to the workshop. Alejandro is an economist, but works as a carpenter for a living. Roberto is a front-end developer and environmental activist that links the preservation of the mountains and forests with the rights of the indigenous people of Tepoztlán. A second Alejandro is a high school senior involved with his neighborhood committee, he wants to study to become a mechatronics engineer. Finally, Oscar is a systems engineer and part of the Forest Ranger Association of Tepoztlán. All of them are native to Tepoztlán and value art as an expression of freedom. They are pretty aware of the contradictions and tensions that their hometown hosts.

The venue was Fernando Martín Juez’s house in the Santa Cruz neighborhood near the west mountain side. Fernando was an architect and designer that appointed his house to become a Cultural Center after his passing. He made the necessary arrangements for an association of friends and neighbors to manage the place and make it a contribution to the people of Tepoztlán. Unfortunately, the funds he left to kickstart activities are being held hostage by a bank (legal action has moved slowly), and the doors have stayed shut except for some isolated events (of which ours is an example). The house has an exotic architecture, a rich color palette, and is full of little artifacts that Fernando collected. It was really a nice place to held the workshop and could become a spot for regular live coding sessions.

The workshop

For the first half of the workshop I gave an introductory talk. First we discussed free and open source software as a strategy to harness community efforts and build people centered technology. Then I introduced the broader live coding practice, sharing some online references, and explained what it meant in the context of computer music. This set the stage to introduce Tidal’s architecture. Before the break, we watched a video performance of Alex McLean (Tidal’s creator) doing a from-scratch session. The slide presentation is available here.

After cookies and coffee, the second part of the workshop was about getting hands-on. I briefly introduced Tidal’s installation procedure with reference to the official documentation for them to attempt an installation at home. Then I made a live demonstration showing the basics of sound reproduction, the mini-notation and some pattern transformations (like fast, slow, (<~), jux and rev). I also talked about function’s inputs and outputs, to provide a better understanding of Tidal’s syntax. Finally we ran an estuary session for collective improvisation. It was fun seeing them go wild with the few functions I showed them.

Aftermath

In this first workshop I might have overwhelmed the participants by showing too much notation too soon. Next time we could do short solo test rounds when introducing syntax elements. This might improve the understanding of all and help build confidence. Furthermore, those rounds could be structured by following an introductory tutorial.

This was fun and I hope more people join, but I know developing a practice community takes time. It’s not easy for people to commit, specially with everyone being so busy. I’ll keep making the call so anyone near looking for something like live coding can find us.

Workshop pictures and details (in spanish).

Btrfs en Garuda Linux

Fue al instalar Garuda Linux en mi desktop que empecé a indagar en el tema. Una de sus características emblemáticas es el uso de snapshots de Btrfs como estrategia de recuperación del sistema:² En caso de que el sistema se rompa, lo cual sucede en ocasiones al actualizarlo, se puede acceder a una lista imágenes previas del sistema desde el menú arranque (GRUB). Estas imágenes (las snapshots) se toman de manera automática antes y después de cada actualización del sistema. Esta característica específica permite utilizar Arch Linux, en la que se basa Garuda,³ de manera confiable. Arch es una distribución que (valga la redundancia) distribuye el software directo desde los repositorios de sus desarrolladores (upstream) de manera continua.⁴ La ventaja: siempre se tienen los ultimos arreglos, parches de seguridad y características. La desventaja: las cosas pueden salir mal y un programa o todo el sistema puede dejar de funcionar. Ambas son razones por las que Arch Linux es una distribución considerada exclusiva para usuarios de Linux expertos o entusiastas.⁵ Btrfs tiene la capacidad de crear snapshots con un costo computacional prácticamente nulo.⁶ Explicar que es exactamente una snapshot en Btrfs excede la intención de este post;⁷ baste decir que se trata de una imagen (de alguna parte) del sistema que permite revertir los cambios en caso necesario. Así, en caso de que algo se rompa al actualizar el sistema, podemos revertir los cambios sin mayor problema.

Es importante mencionar que estas snapshots no son una una solución de respaldo para la integridad de los archivos (aunque se puede implementar con ellas). Dada la naturaleza de Btrfs, y los sistemas de archivos CoW, si un archivo está corrupto entonces lo está para todas las snapshots que lo comparten.

Tuve que investigar estas cosas debido a que cuando instalé Garuda cometí un error inocente. Decidí hacerle caso a un video tutorial de instalación en que se creaba una partición Btrfs separada para guardar los archivos personales (/home). Experiencias previas con otras distribuciones de Linux me habián enseñado la ventaja de tener particiones separadas para los archivos del sistema (/) y los archivos personales. Sin embargo esto no aplicaba de la misma manera en Garuda. Al hacer la partición, evité que el instalador de Garuda ubicara /home en su propio subvolumen. Los subvolúmenes de Btrfs son similares a una partición, pues permiten administrarla de manera independiente gracias a que establecen un tipo de división lógica, con la capacidad extra de acceder al almacenamiento disponible de forma dinámica.⁸ En Garuda se crean por defecto snapshots de /, cada vez que se hace una actualización del sistema. Para ilustrar como funciona esto hay que considerar el arreglo de subvolúmenes que hace Garuda al instalar el sistema:⁹

La función de este arreglo de subvolúmenes es omitir los directorios correspondientes de las snapshots de /. Estos contienen archivos que no conviene revertir al volver a un estado anterior del sistema. /home contiene los archivos y configuraciones personales de los usuarios. /root es análogo a /home para el usuario root. /var/cache contiene archivos transitorios de las aplicaciones. /var/log es para los registros del sistema. /var/tmp contiene archivos temporales que las aplicaciones preservan entre reinicios. /srv contiene archivos relacionados con servicios de red proporcionados por el sistema.¹⁰

Tener /home en una partición separada me impidía administrarla con las herramientas de Garuda que dependen de este arreglo, aunque la partición fuera también Btrfs. Además me empecé a quedar con espacio limitado en el disco para mis archivos. La solución que encontré a esto, evitando reinstalar todo el sistema, está documentada en el foro de Garuda.

Respaldar Doom Emacs

Lograr utilizar lo aprendido sobre Btrfs para idear una simple estrategia para respaldar mi editor de texto me inspiró a escribir este post. Utilizó Doom Emacs: una esquema de configuración para el clásico editor de texto hacker Emacs. El problema con Doom es similar a Arch: muchos de los paquetes se actualizan regularmente siguiendo al upstream, además de que la configuración de Emacs puede ser temperamental per se. Esto me ha llevado en muchas ocasiones (significativamente más de las que me han sucedido con Arch), a que Doom deje de funcionar después de una actualización. La siguiente estrategia sólo aplica a sistemas operativos tipo-unix donde /home/user (denotado ~) es (parte de) un sistema de archivos Btrfs.

La estrategia

Lo primero es mudar Doom Emacs a un subvolumen, para ello hay que:

Cambiar el nombre del directorio donde se guardan los componentes de Doom,

mv ~/.emacs.d ~/.emacs.d.bak

crear un subvolumen para la nueva ubicación con el nombre que liberamos

sudo btrfs subvolume create ~/.emacs.d

y copiar todos los archivos (con sus propiedades) a la nueva ubicación:

cp -a ~/.emacs.d.bak/* ~/.emacs.d

Este último paso es relativamente innecesario, pues Doom es declarativo y su especificación se encuentra en ~/.doom.d:¹¹ bastaría correr doom sync -u para volver a poblar esta ubicación. Sin embargo es una descarga grande, que toma algo de tiempo y que podemos omitir.

Si Doom está funcionando correctamente, podemos borrar el respaldo con rm -rf ~/.emacs.d.bak.

La estrategia consiste en crear una snaphot de solo escritura, o read-only,⁷ antes una actualización.

sudo btrfs subvolume snapshot -r ~/.emacs.d/ ~/.emacs.d.bak.ro

En caso de que la actualización deje a Doom fuera de combate, los siguientes pasos lo reviertiran a su estado anterior:

1. Borrar la configuración defectuosa: sudo btrfs subvolume delete ~/emacs.d/
2. Restaurar la vieja configuración: sudo btrfs subvolume snapshot ~/.emacs.d.bak.ro ~/.emacs.d

Doom Emacs es un editor fantástico, y ahora no tengo reservas en actualizarlo más cotidianamente. Por su parte Btrfs me ha demostrado las posbilididades de los sistemas de archivos.

Qué pedo Mundo

y el mundo surgió del caos primigenio.