Awesome Cabal

A curated list of awesome resources for the Haskell Cabal build tool.

Cabal — Common Architecture for Building Applications and Libraries — is the tool to build and maintain Haskell packages.

Table of Contents

• Resources
• Installation
• Introduction
• Scaffolding
• Cabal Configuration Format
• Components
• Backpack
• PVP
• Cabal Assistants
• CI
• Integration
• Custom Setup
• OS Manifests
• IDE
• Cross Compilation
• Cabal for Development
• Cabal in GSoC
• History
• Community

Resources

• Official website
• Official documentation
• haskell/cabal: Official GitHub source repository.

Installation

There are various means of installing Cabal. Depending on your operating system and prefered method, you can choose a suitable way to do that.

• ghcup: Haskell toolchain installer for Linux and macOS. Use ghcup install-cabal command to install Cabal. Refer to the documentation for more details.
• HVR ppa: PPA for Ubuntu that includes releases of Cabal.
• Windows setup: The easiest way to setup a Haskell environment on Windows using Chocolatey.
• Download binary: Install Cabal on all operating systems from sources or by downloading the binary.
• CabalChoco: Chocolatey sources for pure Cabal installs on Windows.
• Debian packages: Install packages built specifically for Debian 9 (Stretch).
• macOS setup: Python script to install Cabal on macOS.
• ghcups: ghcup for PowerShell on Windows.

Blog posts

• Managing GHC versions with ghcup: How to install different GHCs and Cabal.

Introduction

Write-ups and examples that could help to get into Cabal and start using it.

• Getting started with Haskell and Cabal
• Intoduction: Official documentation's introduction.
• Haskell build tools (by Kowainik): Description of the basic workflows with the main Haskell build tools. You can go straight to the Cabal section of the post.
• Introduction to Cabal (video): In this video Haskell at Work explores the basics of Cabal including the family of new- commands.
• Haskell Aliases: Shell aliases for Haskell build tools for higher productivity.
• Organizing Our Package: Walk through the process of creating and managing a new Haskell project.
• Making the most of Cabal: Showcase of different Cabal features.

Scaffolding

• Quick start: Using cabal init command to create a project.
• summoner: CLI tool for scaffolding fully configured batteries-included production-level Haskell projects.
• summoner-tui: TUI tool for scaffolding fully configured batteries-included production-level Haskell projects.
• hi: Generate scaffold for cabal project.
• example-cabal-project: A simple example project using cabal-install, Nix, and direnv.

Cabal Configuration Format

.cabal files use a special format to specify package configurations.

• Docs: Official documentation on the package description format.
• CHANGELOG: Package description format specification history.
• Minimal cabal files: Explanation of the minimal possible cabal configuration.
• cabal-fmt: CLI tool to format .cabal files.
• cabal-info: Simple command-line interface to read and output information from the .cabal file. (archived, Cabal-1.x only)

Components

Useful information on various Cabal components. These could be useful blog posts on specific features, or description of handy parts of the Cabal specification.

• Common Stanzas: Blog post about Cabal's common stanzas feature.
• Multiple Libraries: Blog post about Cabal's multiple libraries feature.
• Foreign libraries: Blog post about Cabal's foreign libraries feature.
• Foreign libraries example: Example usage of foreign libraries.
• source-repository-package: Specifying packages from remote version control locations (e.g. how to use GitHub dependencies in the Cabal packages).
• cabal gen-bounds: A command to generate lower and upper bounds for dependencies in the .cabal file.
• cabal-bounds: A command line program for managing the bounds/versions of the dependencies in a cabal file.
• cabal-cargs: A command line program for extracting compiler arguments from a cabal file.
• Mix-ins: Usage of the Cabal's mixin feature to replace default Prelude.

Backpack

Backpack is a feature that allows implementing mix-in libraries in Haskell. Mix-in libraries can have signatures which permit implementations of values and types to be deferred, while allowing a library with missing implementations to still be type-checked.

Official documentation

• Edward Z. Yang thesis
• GHC Wiki: Backpack
• GHC User Guide: Module Signature
• Cabal user guide: signatures field
• Cabal user guide: mixins field

Tutorials

• Edward Z. Yang blog: Blog posts about Backpack implementation and usage from the Backpack author.
• Picnic: Put containers into backpack (by Kowainik): This blog post walks the reader through the Backpack implementation of the uniform interface for containers (Maps and Sets).
• Really small Backpack example: A small tutorial on the very basics of the Backpack module system.

Libraries

• backpack-str: Signatures for string types.
• reflex-backpack: Backpack implementation of Reflex.
• containers-backpack: Signatures for various containers (e.g. Map, HashMap, etc.)
• streamy: Signatures for streaming libraries.
• unpacked-containers: Unpacked sets and maps exploiting Backpack's ability to unpack through signatures.

Talks

• Backpack to Work (by Edward Z. Yang)
• Picnic: put containers into a Backpack (by Dmitrii Kovanikov)

PVP

It is recommended for Haskell packages to follow PvP — Package versioning Policy.

• PVP: Official Haskell documentation on versioning.
• pvp: The GitHub repository to create issues against.
• policeman (by Kowainik): Policeman assists to properly choose the next version number according to PVP (Packaging Version Policy) for the Haskell packages based on the semantical changes to the interface.
• check-pvp: Check whether module and package imports conform to the PVP.

Cabal Assistants

CLI tools that provide additional interface to cabal-install.

• cabal-install: The command-line interface for Cabal and Hackage.
• vabal: The cabal companion that leverages Cabal's capabilities of working with different GHC versions.
• hkgr: Tool to help make new releases of Haskell packages, with commands for git tagging, pristine sdist, and uploading to Hackage.
• releaser: Automation of Haskell package release process.
• iridium: This tool aims to automate several typical steps when uploading a new package version to Hackage.
• Haskell package QA: New things in Haskell package QA.
• cabal-plan: Library and utility for processing cabal's plan.json file.
• cabal-extras: A tool suite to aid Haskell development using cabal-install.
• cabal-helper: Give Haskell development tools access to the same environment which build tools such as Cabal normally provide to the compiler.
• cabal-sort: Given a number of cabal package files, this program reads all those files and emits them topologically sorted according to their dependencies.
• mafia: Lightweight but opinionated wrapper around Cabal that makes working on Haskell projects fun and easy.
• cabal-scripts: Collection of Bash Shell scripts for support of Cabal package development.
• cabalish: Provides access to the cabal file data for shell scripts.
• cab: A MacPorts-like maintenance command of Haskell Cabal packages.
• cabal-edit: A utility for managing Hackage dependencies from the command line.
• cabal-clean: Removes compilation artefacts in dist-newstyle/build from older versions of the package or superseded minor versions of GHC.

Dependencies analysers

• cabalgraph: Generate pretty graphs of module trees from .cabal files.
• cabal-progdeps: Show dependencies of program being built in current directory.
• weeder: Tool for detecting redundant Cabal package dependencies that uses .hie files introduced in GHC-8.8.
• packdeps: A library and command line tool for checking if the upper bounds in your Cabal package's dependency list excludes the newest package available.
• jailbreak-cabal: Strip version restrictions from build dependencies in the .cabal files.

CI

Information about how to set up Continious Integration on Haskell packages.

Travis

• Dead simple Haskell Travis settings for cabal and stack: Blog post about Travis CI settings for Haskell projects with Cabal and Stack.
• haskell-ci: Cabal package script generator for Travis CI.
• Testing with Travis: Blog post about how to quickly and easily set up continuous integration for your open source Haskell projects hosted on GitHub.

AppVeyor

• Haskell & AppVeyor Chocolatey Introduction: Stey-by-step description of building Haskel packages with Chocolatey and Cabal on AppVeyor CI.
• appveyor.yml example: Minimal working example of the appveyor.yml configuration file.

GitHub Actions

• Dead simple cross-platform GitHub Actions for Haskell: Blog post about cross-platform GitHub Actions CI settings for Haskell projects with Cabal and Stack.
• haskell-ci: Cabal package script generator for GitHub Actions CI.
• setup-haskell: Set up your GitHub Actions workflow with a specific version of Haskell (GHC and Cabal).
• actions/cache: This action allows caching dependencies and build outputs to improve workflow execution time.
• cabal-plan-bounds: Never write bounds manually, instead derive them from what CI is actually testing.

Circle CI

• Circle CI orbs: Haskell Orb that Builds a Haskell application using Cabal on Circle CI.

Generic CI

• packcheck: Universal build and CI testing for Haskell packages. Can produce configurations for Travis, AppVeyor and Circle CI.
• cabal-cache: Tool for caching built cabal new-build packages.
• hw-ci-assist: CI Assistant for Haskell projects which implements package caching.

Docker

• docker-ghc: GHC + Cabal docker image.
• ghc-musl: Docker image with GHC+musl and Cabal for static executables.
• Docker Haskell example: Multi-stage docker build of Haskell webapp.

Deployment

• Heroku buildpack GHC: Buildpack for deploying Haskell apps to Heroku.
• Haskell on Heroku: This tutorial shows how to develop a simple Haskell web app and deploy it to Heroku.

Integration

Cabal integration with other configuration languages and formats.

• dhall-to-cabal: Compiles Dhall expressions to Cabal files.
• cabal-to-dhall: The opposite of dhall-to-cabal. Compiles Cabal to Dhall expressions.
• cabal2nix: Convert Cabal files into Nix build instructions.
• nix2cabal: The opposite of cabal2nix. It lets you define a Haskell package in Nix and generate a Cabal file using that definition.
• cabal2bazel: A tool to help with fetching Cabal packages from Hackage and importing them as packages into cabal2bazel.
• jenga: Generate a cabal.freeze file from a stack.yaml.
• stack2cabal: Convert stack projects to cabal.project + cabal.project.freeze.
• shake-cabal: A library for using shake alongside Cabal.

Custom Setup

Setup.hs helpers to use in custom-setup stanzas with the Custom build type.

• Dependencies for Cabal Setup.hs and other goodies
• autopack (by Kowainik): Automatically discovers Haskell modules and populates exposed-modules.
• proto-lens-setup: Cabal support for codegen with proto-lens.
• liquidhaskell-cabal: Liquid Haskell integration for Cabal and Stack.
• liquidhaskell-cabal-demo: Demo of Liquid Haskell integration for Cabal and Stack.
• cabal-build-programs: Lets you use custom Cabal fields for executable dependencies.
• chs-cabal: Cabal with c2hs dependencies.
• ats-setup: ATS scripts for Cabal builds.
• asset-bundle: A build-time Cabal library that bundles executables with assets.
• cabal-bundle-clib: Bundling C/C++ projects in Cabal package made easy.
• cabal-toolkit: Helper functions for writing custom Setup.hs scripts.
• quipper-cabal: Some functions to aid in the creation of Cabal packages for Quipper.

OS Manifests

Tools to generate system packages meta information from Haskell packages.

• cabal-debian: Create a Debianization for a Cabal package.
• cabal-flatpak: Generate a FlatPak manifest from a Cabal package description.
• cabal-macosx: Cabal support for creating Mac OSX application bundles.
• cabal-rpm: RPM packaging tool for Haskell Cabal-based packages.
• cabal2spec: Convert Cabal files into rpm spec files.
• cblrepo: Tool to simplify managing a consistent set of Haskell packages for distributions.
• exherbo-cabal: Generates package description from .cabal files in format of exheres-0 for Exherbo Linux.
• hackport: A command line tool to manage an overlay of Gentoo ebuilds that are generated from a hackage repo of Cabal packages.

IDE

Helper tools for Cabal support in various Integrated Development Environments.

• Haskell IDE Setup with cabal and nix: Haskell setup for vscode with cabal and nix.
• codex: A ctags file generator for Cabal project dependencies.
• vim-cabal-indent: .cabal files indentation plugin for Vim.
• vim-syntax-haskell-cabal: Cabal syntax highlighting plugin for Vim.

Cross Compilation

• The Haskell Cabal and cross compilation: Cross compiling packages with Cabal.

Cabal for Development

Haskell libraries to parse and work with files in the Cabal format.

• Cabal: Official library to parse and analyze .cabal files.
• cabal-lenses: Lenses and traversals for the Cabal library.
• cabal-install-parsers: Parsers for .cabal, cabal.project, cabal.config and 01-index.tar files.
• cabal-file-th: Template Haskell expressions for reading fields from a project's cabal file.
• cabal-test-quickcheck: QuickCheck for Cabal.
• cabal-doctest: A Setup.hs helper for doctests running.
• doctest-extract: Standalone extraction of doctest code. Optionally emits a list of Test modules for insertion in a Cabal package description.
• simple-cabal: Find and read .cabal files, and a Cabal dependency compatibility layer.
• cabal-file: Cabal file access.

Cabal in GSoC

Work on Cabal during Google Summer of Code.

• GSoC 2018: cabal new-{install,repl,run,clean,sdist}, Cabal scripts: Description of work to finish bringing Cabal’s Nix-style local builds (the new- commands, at least for now) up to parity with the old stateful methodology of using cabal-install.
• GSoC Cabal Nix: How bringing Nix-style package management facilities to cabal can solve various cabal problems and help in effective mitigation of cabal hell.

History

• Old Cabal: Really old Cabal stuff.
• Announcing New Cabal: cabal new-build, also known as “Nix-style local builds”, is a new command inspired by Nix that comes with cabal-install 1.24.
• Cabal 2.0: What's new in Cabal and cabal-install 2.0.

Community

• cabal-devel: Development discussion takes place on the cabal-devel mailing list.
• Libraries mailing list: Questions can be sent to the Haskell libraries mailing list.
• Issue reporting: GitHub issue creation page.

Contribute to this repository

Improvements to the Awesome Cabal list are more than welcome. Please read the contributing guidelines, go ahead and make the difference!

License