Skip to content
Tutorials Center
My learning

Topics

Lesson 37 of 57 ยท Modules, packages and tooling

Cabal, Stack and Packages

Create a Haskell project with Cabal or Stack, read a .cabal file, add dependencies from Hackage and Stackage, and learn the standard project layout.

A single .hs file is fine for learning, but real programs have several modules, depend on libraries written by other people, and need tests. Haskell has two mainstream build tools for that job: Cabal and Stack. Both read the same project description file, a .cabal file, and both call GHC to do the compiling. They differ in how they choose the versions of your dependencies.

This lesson is a tour of the files and commands you will meet in almost every Haskell project. Haskell is not installed on this site, so the real commands and files are read-only; the runnable examples are JavaScript stand-ins that model how version ranges and .cabal fields work. If you have not installed GHC yet, start with Installing GHC and using GHCi.

Three words, three jobs

Package A named, versioned bundle of modules.
Build tool Cabal or Stack. It runs GHC for you.
Package index Hackage hosts the packages.

A project is itself a package.

1 / 2

Packages, Hackage and Stackage

A package is the unit of distribution in Haskell. It has a name, a version and a list of modules it exposes. Hackage is the public package index where anyone can upload a package; when you write build-depends: text, Cabal downloads text from there.

Stackage is a curated subset of Hackage. The Stackage maintainers pick one version of each package such that they all compile together, then publish that set as a snapshot. A long-term-support snapshot is named like lts-NN.M and is tied to one GHC version. Stack uses a snapshot so that "it built yesterday" means "it builds today".

Cabal takes the other approach: it runs a dependency solver. Given the version ranges in your .cabal file, it searches Hackage for a set of versions that satisfy everybody. You can also point Cabal at a Stackage snapshot if you want the best of both worlds.

Starting a project with Cabal

Cabal is installed together with GHC by GHCup. Create a project in a new folder:

Terminal
mkdir hello-haskell
cd hello-haskell
cabal init --interactive

The questions ask for the package name, whether you want a library, an executable or both, and the language. The result is a small tree. A typical layout after you have added a library and a test suite looks like this:

TEXT
hello-haskell/
โ”œโ”€โ”€ hello-haskell.cabal
โ”œโ”€โ”€ app/
โ”‚   โ””โ”€โ”€ Main.hs
โ”œโ”€โ”€ src/
โ”‚   โ””โ”€โ”€ Greeting.hs
โ””โ”€โ”€ test/
    โ””โ”€โ”€ Spec.hs

Common commands:

Terminal
cabal build          # compile everything
cabal run            # build and run the executable
cabal repl           # open GHCi with the project loaded
cabal test           # run the test suite
cabal update         # refresh the list of packages from Hackage

The first cabal build downloads and compiles your dependencies. Later builds only recompile what changed.

Reading a .cabal file

The .cabal file is plain text with field: value lines grouped into stanzas. Here is a small one:

CABAL
cabal-version:      3.0
name:               hello-haskell
version:            0.1.0.0
synopsis:           A tiny greeting tool
license:            MIT
build-type:         Simple

common shared
    default-language: GHC2021
    ghc-options:      -Wall
    build-depends:    base >=4.18 && <5

library
    import:           shared
    hs-source-dirs:   src
    exposed-modules:  Greeting
    build-depends:    text ^>=2.1

executable hello
    import:           shared
    main-is:          Main.hs
    hs-source-dirs:   app
    build-depends:    hello-haskell

test-suite spec
    import:           shared
    type:             exitcode-stdio-1.0
    main-is:          Spec.hs
    hs-source-dirs:   test
    build-depends:    hello-haskell

Key points:

  • library holds reusable code. exposed-modules lists the modules other packages may import; modules you leave out of that list go in other-modules and stay private.
  • executable is a program. main-is names the file that contains main.
  • test-suite is run by cabal test. The type exitcode-stdio-1.0 means "pass if the program exits with code 0".
  • common stanzas hold settings you import into other stanzas, so you do not repeat yourself.
  • hs-source-dirs says where the .hs files live.
  • default-language picks a language edition, which switches on a bundle of GHC extensions.

The base package comes with GHC and contains the Prelude, so almost every stanza depends on it.

Version bounds

Each dependency may carry a version range. The two forms you will see most are:

  • base >=4.18 && <5: any version from 4.18 up to, but not including, 5.
  • text ^>=2.1: the caret operator. ^>=2.1 means "2.1 or newer, but below 2.2", so it follows the Haskell Package Versioning Policy (PVP), in which the first two numbers form the major version and a change there may break your code.

Bounds protect you from a new major release that changes an API. Too tight and the solver cannot find a plan; too loose and a future release can break your build. The PVP is the shared contract that makes those bounds meaningful.

JS Which version does the solver pick? (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The solver prefers the newest version that fits every bound. When two packages in your project ask for incompatible versions of a third, Cabal reports it as a failed plan and shows which bounds clashed.

Starting a project with Stack

Stack is installed separately (GHCup can install it too). It manages its own copy of GHC per snapshot.

Terminal
stack new hello-haskell
cd hello-haskell
stack build
stack run
stack test
stack ghci

A Stack project has two description files. Stack itself reads stack.yaml, and a package inside it still has a .cabal file (generated from package.yaml in some templates, using the hpack format, which is a shorter YAML spelling of the same information).

YAML
snapshot: lts-24.0
packages:
  - .
extra-deps:
  - some-package-1.2.3
  • snapshot names the Stackage snapshot. (Older files call this field resolver; both work.) Check the Stackage website for a current snapshot name instead of copying the one above.
  • packages lists local packages in the project. A monorepo can list several folders.
  • extra-deps pins packages that are not in the snapshot, such as a newer release or one from Git.

With Stack you normally write no upper bounds in build-depends, because the snapshot already fixes the versions.

Adding a dependency

To use a library such as containers or text, you do three things, whichever tool you use:

  1. Add the package name to build-depends of the stanza that needs it.
  2. Rebuild, so the tool fetches and compiles it.
  3. import its modules in your source.

If you skip step 1, GHC reports that the module is hidden or could not be found, even though the package is on your machine. A package that is installed is not the same as a package that is in build-depends. A short tour of the most useful libraries is in Essential Libraries.

Habits that help

  • Put code in the library, keep Main.hs tiny. The executable and test suite both depend on the library, so tests can import the same modules the program uses.
  • Turn on -Wall. It catches unused imports and incomplete patterns early (see Debugging, Profiling and Performance).
  • Commit the .cabal file, and with Cabal also cabal.project.freeze for applications if you want reproducible builds. Do not commit the dist-newstyle/ or .stack-work/ folders.
  • Use cabal repl or stack ghci to experiment with your project's modules interactively.

Modeling a .cabal field list

The next stand-in reads a simplified stanza and extracts its dependencies. It shows that a .cabal file is just structured text: nothing about it is magic.

JS Reading dependencies from a stanza (stand-in)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Real Cabal also understands if conditionals, flags and common imports, but the shape (fields, stanzas, lists separated by commas) is the same.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is Stackage?

    Stackage publishes snapshots (such as LTS releases) in which every package version works with the others. Stack uses them to give reproducible builds.
  2. 2. What does text ^>=2.1 mean in a build-depends line?

    The caret operator follows the Package Versioning Policy: the first two numbers are the major version, so ^>=2.1 allows 2.1.x but not 2.2.
  3. 3. You installed a package but GHC says the module cannot be found. What is the most likely fix?

    Only packages listed in build-depends are visible to a stanza's modules.
  4. 4. Where should most of your code live so that tests can reuse it?

    Both the executable and the test suite can depend on the library, so shared code belongs there.

Summary

  • A package is a named, versioned bundle of modules; Hackage hosts them and Stackage curates compatible snapshots.
  • Cabal solves dependency versions from your bounds; Stack uses a snapshot from stack.yaml. Both read the .cabal file.
  • A .cabal file has stanzas: library, executable, test-suite and shared common blocks.
  • ^>=2.1 follows the PVP: from 2.1 up to, but not including, 2.2.
  • Add libraries to build-depends, then rebuild and import them.
  • Keep the real code in the library and Main.hs small.

Next: Essential Libraries: containers, text, bytestring, vector.