Haskell Cabal Guide — Cabal Build System, Package Configuration, and Distribution

In this tutorial, you will learn about Haskell Cabal Guide. We cover key concepts, practical examples, and best practices to help you master this topic.

Haskell Cabal is the original build tool using .cabal files for package metadata (name, version, dependencies, exposed-modules) -- with commands like cabal build, cabal test, cabal repl, and cabal sdist for building and distributing packages.

Cabal File

-- my-package.cabal
cabal-version: 3.0
name:          my-package
version:       0.1.0.0
author:        DodaTech
license:       MIT

library
  exposed-modules:  MyLib
  build-depends:    base >= 4.7 && < 5
                  , text ^>= 2.0
  hs-source-dirs:   src

executable my-app
  main-is:          Main.hs
  build-depends:    base, my-package
  hs-source-dirs:   app

Building

# Configure and build
cabal build

# Build specific component
cabal build my-package:lib:my-package
cabal build my-package:exe:my-app

# Build with profiling
cabal build --enable-profiling

# Build with optimization
cabal build -O2

# Clean
cabal clean

Testing and REPL

# Run tests
cabal test

# Open REPL with package loaded
cabal repl

# REPL for specific component
cabal repl lib:my-package
cabal repl exe:my-app

# Run executable
cabal run my-app
cabal run my-app -- --args

Distribution

# Create source tarball
cabal sdist
# Creates dist-newstyle/sdist/my-package-0.1.0.0.tar.gz

# Upload to Hackage
cabal upload dist-newstyle/sdist/my-package-0.1.0.0.tar.gz

# Check package validity
cabal check

# Generate documentation
cabal haddock

Common Mistakes

1. Version constraint too strict

base == 4.18.* breaks on GHC 9.8. Use >= 4.7 && < 5 for maximum compatibility.

2. Missing exposed-modules

All library modules must be listed in exposed-modules or other-modules. Omitted modules are not compiled.

3. Forgetting to update version

Increment the version field for each release. cabal check warns about version consistency.

Practice Questions

1. How do you define a library in a .cabal file? Use the library stanza with exposed-modules listing public modules and build-depends for dependencies.

2. How do you run tests with Cabal? cabal test runs the test suite defined in the .cabal file. Use cabal test --test-option=--match for filtering.

3. How do you create a source distribution? cabal sdist creates a .tar.gz in dist-newstyle/sdist/ ready for Hackage upload.

FAQ

{{< faq question="What is Cabal's new-build vs old-build?" >}} New-build (cabal v2-build, default since 3.0) uses Nix-style builds with sandboxed dependencies. Old-build (cabal build --v1) is deprecated. {{< /faq >}}

{{< faq question="How do I freeze dependency versions?" >}} cabal freeze creates cabal.project.freeze with exact version constraints for all dependencies. {{< /faq >}}

{{< faq question="What is cabal.project?" >}} A file for project-level configuration: multiple packages, constraints, and build options. Overrides package-level settings. {{< /faq >}}

What's Next

Now learn about GHCi.