What Cabal Does
Cabal (Common Architecture for Building Applications and Libraries) is Haskell's build system and package format. A .cabal file declares a package's name, version, dependencies with version bounds, exposed modules, and build targets (library, executable, test-suite, benchmark). The cabal command-line tool uses that file plus a dependency-solving algorithm to figure out a consistent set of package versions to install from Hackage, Haskell's central package repository.
Cricket analogy: A .cabal file is like a team's official squad list submitted to the match referee before a series -- it names exactly who's playing (exposed modules), what role each has (library vs executable), and which support staff (dependencies) are required, so nobody discovers a missing player on match day.
Dependency Resolution and Version Bounds
Cabal's constraint solver searches for a single, mutually consistent set of package versions that satisfies every declared dependency bound in the project, following the Package Versioning Policy (PVP) convention where a major version bump (the first two components, e.g. 1.2 to 2.0) signals a potentially breaking API change. A cabal.project file coordinates builds across multiple local packages in a monorepo, and cabal.project.freeze records the exact resolved versions so the same build plan can be reproduced later, which is critical for CI.
Cricket analogy: Cabal's constraint solver picking one consistent set of package versions across a whole project is like a chief selector picking a squad where every player's role is mutually compatible -- you can't select a specialist opener and also require them to keep wicket in the same match.
cabal-version: 2.4
name: my-app
version: 0.1.0.0
build-type: Simple
library
exposed-modules: MyApp.Core, MyApp.Parser
build-depends: base >=4.14 && <5,
text >=1.2 && <2.1,
containers >=0.6 && <0.7
hs-source-dirs: src
default-language: Haskell2010
executable my-app
main-is: Main.hs
hs-source-dirs: app
build-depends: base, my-app
default-language: Haskell2010
test-suite my-app-test
type: exitcode-stdio-1.0
main-is: Spec.hs
hs-source-dirs: test
build-depends: base, my-app, hspec
default-language: Haskell2010
cabal build, run, test, and the Nix-style Local Store
Day-to-day, cabal build compiles all targets, cabal run my-app builds and executes an executable, cabal test runs the declared test-suites, and cabal repl opens an interactive GHCi session with your project's modules loaded. Modern Cabal (the v2- / Nix-style commands, now the default) builds into a global, content-addressed local store keyed by each package's exact configuration, so an identical dependency build is shared across every project that needs it instead of being recompiled per project.
Cricket analogy: The shared, content-addressed package store that cabal build uses across projects is like a national cricket board maintaining one central pool of certified umpires that every domestic match draws from, rather than each state association training its own from scratch.
Run cabal update periodically to refresh your local copy of the Hackage package index -- without it, cabal build may fail to find a newly published package version or resolve to stale metadata even though the actual package exists on Hackage.
Cabal vs Stack
Cabal resolves dependencies dynamically against the full Hackage index using its constraint solver and whatever bounds you declare, which is flexible but occasionally produces version-resolution conflicts on large dependency graphs. Stack instead points at a curated Stackage snapshot -- a large set of package versions that have already been built and tested together -- trading some flexibility for a simpler, more predictable 'known-good' dependency story, which is why many teams choose Stack for onboarding new developers and Cabal for fine-grained control over exact versions.
Cricket analogy: Stack's curated Stackage snapshot is like a pre-selected touring squad that's already been vetted to play well together, while Cabal's solver is like a chief selector assembling a fresh combination from the entire domestic pool for every single match, more flexible but requiring more judgment calls.
Mixing a stack.yaml-managed project with ad-hoc cabal install --lib commands on the same machine can produce confusing 'package not found' or version-mismatch errors, because Stack and Cabal maintain separate package databases and resolution strategies -- pick one tool per project and stick with it.
- A .cabal file declares a package's name, version, dependencies with version bounds, and build targets (library, executable, test-suite, benchmark).
- Cabal's constraint solver picks one mutually consistent set of dependency versions across the whole project from Hackage.
- Version bounds like
base >=4.14 && <5follow the Package Versioning Policy (PVP), where a major bump signals breaking changes. cabal.projectcoordinates multi-package local builds;cabal.project.freezepins exact versions for reproducible builds.- Modern cabal (v2- / Nix-style) uses a global, content-addressed store so identical builds are shared across projects, not duplicated.
cabal build,cabal run,cabal test, andcabal replcover the core build-run-test-explore workflow.- Run
cabal updateregularly to refresh the local Hackage index before resolving new dependencies.
Practice what you learned
1. What is the primary purpose of a .cabal file?
2. What does a version bound like `base >=4.14 && <5` communicate under the Package Versioning Policy (PVP)?
3. What is the purpose of `cabal.project.freeze`?
4. How does Cabal's Nix-style (v2-) local build store improve efficiency across multiple projects?
5. What command should you run before building if you suspect Cabal can't see a newly published Hackage package version?
Was this page helpful?
You May Also Like
Testing Haskell Code
Learn how to write unit tests, property-based tests, and doctest examples for Haskell code using HUnit, Hspec, and QuickCheck.
Lazy Evaluation in Haskell
How Haskell's non-strict evaluation model defers computation until results are needed, enabling infinite structures but requiring care around space leaks.
Error Handling in Haskell
Learn how Haskell represents failure explicitly using Maybe, Either, and exceptions, and when to reach for each approach.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics