LinuxCommandLibrary

cabal

Build and manage Haskell projects

TLDR

Search and list packages from Hackage

$ cabal list [search_string]
copy

Show information about a package
$ cabal info [package]
copy

Download and install a package
$ cabal install [package]
copy

Create a new Haskell project in the current directory
$ cabal init
copy

Build the project in the current directory
$ cabal build
copy

Run tests of the project in the current directory
$ cabal test
copy

SYNOPSIS

cabal command [options] [arguments]
Common modern commands include:
cabal new-build - Builds the current project.
cabal new-run - Runs an executable from the project.
cabal new-install - Installs a package or executable.
cabal update - Updates the package index from Hackage.
cabal repl - Starts an interactive GHCi session.
cabal init - Initializes a new Cabal project.

PARAMETERS

new-build (or v2-build)
    Builds the current project or specified components, creating a local, sandboxed build environment. This is the recommended modern build command.

new-run (or v2-run)
    Builds and executes a specified executable from the project, respecting its dependencies.

new-install (or v2-install)
    Builds and installs a package or executable into the user's local bin path, often in a sandboxed manner.

update
    Downloads and updates the latest package index from Hackage, essential for finding new packages and dependencies.

repl
    Starts an interactive GHCi session for the project, automatically configuring it with the project's dependencies.

init
    Interactively creates a new .cabal project file, guiding the user through basic setup for libraries or executables.

configure
    Configures the project for building (legacy command, largely superseded by new-build/v2-build).

build
    Builds the project (legacy command, superseded by new-build/v2-build).

install
    Installs a package globally or locally (legacy command, superseded by new-install/v2-install for project-specific installations).

--help
    Displays help information for the cabal command itself or for a specific subcommand.

--version
    Shows the cabal-install tool version.

DESCRIPTION

cabal (short for Common Architecture for Building Applications and Libraries) is the primary build system and package manager for Haskell. It facilitates the compilation, installation, and management of Haskell packages and projects. Developers use cabal to define project dependencies, compile source code, run tests, and generate documentation. It works in conjunction with the Glasgow Haskell Compiler (GHC) to resolve dependencies from Hackage (the central Haskell package archive), build executables and libraries, and manage different project configurations. While historically known for potential "dependency hell," modern cabal versions, especially with cabal new-build (now cabal v2-build) commands, offer robust sandboxing and reproducible builds, making it a powerful and widely used tool in the Haskell ecosystem. It manages project-specific environments and global installations.

CAVEATS

Dependency Hell: Older cabal versions were notorious for dependency conflicts due to a lack of robust sandboxing. While new-build / v2-build significantly mitigates this, careful dependency management is still important.
Global vs. Sandboxed Builds: cabal can install packages globally, which can lead to conflicts, or locally within a project (sandboxed), which is the recommended modern approach via new-* commands.
Comparison with Stack: Many Haskell developers use Stack instead of or alongside cabal for project management. Stack provides opinionated, reproducible builds based on "LTS Haskell" snapshots, offering a different approach to dependency management.

CONFIGURATION FILES

cabal projects are defined by .cabal files (e.g., my-project.cabal), which specify project metadata, dependencies, executables, and libraries. Modern cabal also often uses cabal.project files to define multi-package projects and global configuration.

HACKAGE

cabal interacts primarily with Hackage, the central repository for Haskell packages. The cabal update command fetches the latest package index from Hackage, and cabal install (or new-install) downloads and builds packages listed there.

HISTORY

cabal has been the standard build tool for Haskell since the early 2000s. Originally, the cabal package format and the cabal-install tool were separate. Early versions of cabal-install relied heavily on global package databases, often leading to "dependency hell" where conflicting dependencies between different projects would break builds. This led to the creation of alternative tools like Stack.
To address these issues, significant improvements were introduced with the "new-build" commands (now often referred to as "v2-build" commands) starting around cabal-install version 1.24. These commands brought robust local sandboxing, improved build reproducibility, and a more user-friendly workflow, aiming to provide a first-class developer experience akin to tools in other ecosystems. The development continues to be community-driven, improving performance, dependency resolution, and integration with the wider Haskell ecosystem.

SEE ALSO

ghc(1), stack(1), npm(1), pip(1), maven(1)

Copied to clipboard