The Haskell Cabal | Overview (original) (raw)

Cabal: Common Architecture for Building Applications and Libraries

Introduction

Cabal is a system for building and packaging Haskell libraries and programs. It defines a common interface for package authors and distributors to easily build their applications in a portable way. Cabal is part of a larger infrastructure for distributing, organizing, and cataloging Haskell libraries and programs.

The term cabal can refer to either: cabal-the-spec (.cabal files), cabal-the-library (code that understands .cabal files), or cabal-the-tool (the cabal-install package which provides the cabal executable); usually folks are referring to cabal-the-tool when they say cabal.

Install/Upgrade cabal

The recommended method to install the cabal executable is to use ghcup, which can manage multiple versions of cabal on Linux, Mac and Windows. Alternatively, you can install cabal using your distribution's package manager (if you are using Linux or Mac), or download the source or prebuilt binary from the Download page.

If you have installed cabal using ghcup, then you can also upgrade it using ghcup. If you installed the cabal executable using a different method, you can upgrade it by running: cabal install cabal-install
This will install the cabal executable in cabal's installdir (usually ~/.local/bin). In order to use this executable, you have to make sure that this directory appears in the $PATH variable before the location where your current cabal executable is located. You can check which version of the cabal executable you are running by executing the command below.cabal --version

If the update failed for any reason, see the Update Troubleshooting section below.

Quick Start Guide

Start by installing the cabal executable (see the previous section) and the Haskell compilerghc. It is also recommended to use ghcup to install ghc.

Starting a new project

mkdir myproject && cd myproject cabal init cabal run

• The cabal init command will create all the needed files for an executable.
• The cabal run will build and run the executable in the project.

Documentation

• Cabal User Guide
• FAQ and Troubleshooting - commonly encountered issues and how to resolve them

Related Pages

• Hackage: the Haskell Package Database
• Updating packages to work with recent Cabal and GHC versions
• Browse open issues or report a new bug
• Source code for development versions.
• Questions can be sent to the Haskell libraries mailing list
• Development discussion takes place on the cabal-devel mailing list
• Applications and Libraries for Haskell

Update Troubleshooting

Before you try anything else, you may want to refresh the package index: cabal update
If you already have a new-ish version of cabal you can use the v2/new commands. Try the following: cabal new-install Cabal cabal-install
If this works, update the cabal command on your $PATH with the version installed. Some alternative installation methods from source code are described in the Cabal source repository.

Particularly when upgrading from old versions, you may see:

ERROR: cabal: The following packages are likely to be broken by the reinstalls: ...
Use --force-reinstalls if you want to install anyway.

This can happen if your package archive gets into a broken state. How to fix this depends on the situation. Sometimes re-running the command with--force-reinstalls works, other times you have to remove your whole package archive and start over again.

Thankfully this doesn't happen very often. If you run into this issue and you want to preserve your local package archive, ask a question, e.g., on StackOverflow.