cabal
Build and manage Haskell projects
TLDR
Search and list packages from Hackage
Show information about a package
Download and install a package
Create a new Haskell project in the current directory
Build the project in the current directory
Run tests of the project in the current directory
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.