A Cabal project, offline

What Cabal is for

ghc Main.hs is enough for one folder of modules. A package adds the things a project needs around them: a name and a version, the list of dependencies, the folders of the sources, the things to install, and the commands that rebuild only what changed. Cabal is the tool and the file format, and it comes with GHC in this container:

cabal --version
ghc --version

cabal-install version 3.16.0.0
compiled using version 3.16.0.0 of the Cabal library (in-tree)
The Glorious Glasgow Haskell Compilation System, version 9.10.3

The important fact of this container is that there is no network and no package index: cabal prints a warning about the missing package list, and a build works only when every dependency is one of the boot libraries that came with GHC. That is enough for this lesson and the next two, which use base only.

cabal init in a folder

cabal init asks questions and writes a project. With -n --minimal --exe it takes the defaults, writes a small .cabal file and a Main.hs:

mkdir mindemo
cd mindemo
cabal init -n --minimal --exe

Warning: The package list for 'hackage.haskell.org' does not exist. Run 'cabal
update' to download it.
[Info] Guessing dependencies...
[Info] Using cabal specification: 3.16
[Warn] unknown license type, you must put a copy in LICENSE yourself.
[Info] Creating fresh file CHANGELOG.md...
[Info] Creating fresh directory ./app...
[Info] Creating fresh file app/Main.hs...
[Info] Creating fresh file mindemo.cabal...
[Warn] No synopsis given. You should edit the .cabal file and add one.
[Info] You may want to edit the .cabal file and add a Description field.

The folder now holds mindemo.cabal, CHANGELOG.md and app/Main.hs. The two warnings are honest: the package list is missing because there is no network, and the licence is a placeholder because nobody answered the question. A real project fills both in.

The .cabal file

The generated file is short, and every stanza in it is a decision:

cabal-version: 3.16 name: mindemo version: 0.1.0.0 license: NONE author: Unknown maintainer: Unknown build-type: Simple extra-doc-files: CHANGELOG.md common warnings ghc-options: -Wall executable mindemo import: warnings main-is: Main.hs build-depends: base ^>=4.20.2.0 hs-source-dirs: app default-language: Haskell2010

The fields worth knowing before you edit one:

The generated app/Main.hs is a whole program with a module Main (main) where header and one putStrLn; it is the file this lesson builds.

module Main (main) where main :: IO () main = putStrLn "Hello, Haskell!"

cabal build --offline

cabal build --offline

Warning: The package list for 'hackage.haskell.org' does not exist. Run 'cabal
update' to download it.
Resolving dependencies...
Build profile: -w ghc-9.10.3 -O1
In order, the following will be built (use -v for more details):
 - mindemo-0.1.0.0 (exe:mindemo) (first run)
Configuring executable 'mindemo' for mindemo-0.1.0.0...
Preprocessing executable 'mindemo' for mindemo-0.1.0.0...
Building executable 'mindemo' for mindemo-0.1.0.0...
[1 of 1] Compiling Main ( app/Main.hs, dist-newstyle/build/x86_64-linux/ghc-9.10.3/mindemo-0.1.0.0/x/mindemo/build/mindemo/mindemo-tmp/Main.o )
[2 of 2] Linking dist-newstyle/build/x86_64-linux/ghc-9.10.3/mindemo-0.1.0.0/x/mindemo/build/mindemo/mindemo

--offline is what makes the command fail at once instead of waiting for a download. Everything it needs is in the GHC installation, so the build succeeds with the warning. The artefacts live under dist-newstyle/, in a path built from the package name, the GHC version and the component, which is why two projects and two compilers can share one machine.

cabal run --offline mindemo

Hello, Haskell!

cabal run builds if needed and runs the executable with the standard output attached. A second cabal build --offline now says Up to date: Cabal compares the timestamps and the flags and does nothing, which is the whole reason to use it over a shell script.

What needs the network

A dependency that is not in the GHC installation cannot be resolved without an index. Changing build-depends to include aeson gives this error before any compilation starts:

cabal build --offline

Warning: The package list for 'hackage.haskell.org' does not exist. Run 'cabal
update' to download it.
Resolving dependencies...
Error: [Cabal-7107]
Could not resolve dependencies:
[__0] trying: demo-0.1.0.0 (user goal)
[__1] unknown package: aeson (dependency of demo)
[__1] fail (backjumping, conflict set: aeson, demo)
After searching the rest of the dependency tree exhaustively, these were the goals I've had most trouble fulfilling: demo, aeson

On a machine with a network the same line works after cabal update, which downloads the index, and cabal build then downloads and compiles aeson and its dependencies into the store. The packages that are available here without any of that are the boot libraries of GHC:

ghc-pkg list prints the same list from the compiler's point of view, and the lesson on the install left it as the check of a working installation. The next lesson puts a library, an executable and a test suite into one package, all of them on boot libraries only.

Exercises

  1. Create a package with cabal init -n --minimal --exe and change the generated program to print its arguments.
  2. Add -O2 to the ghc-options of the common stanza and rebuild.
  3. Run cabal build --offline -v and find the ghc command line Cabal used.
  4. Find the built executable under dist-newstyle/ and run it without Cabal.
  5. Add text to the dependencies, use Data.Text in the program and rebuild offline.
  6. Explain the difference between cabal build and cabal run.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does the .cabal file of a package list?

    Answer

    The name, the dependencies and the components to build

    The .cabal file is the package description: identity, dependencies and the library, executables and test suites.

  2. What does cabal build --offline do?

    Answer

    Builds with the local packages only and fails instead of downloading

    The flag forbids network access, so a missing dependency is an error rather than a download.

  3. Where do the build artefacts go?

    Answer

    dist-newstyle/

    Cabal keeps the objects, interfaces and binaries under dist-newstyle, keyed by package and compiler.

  4. What does this program print? module Main (main) where main :: IO () main = putStrLn "Hello, Haskell!"

    Answer

    Hello, Haskell!

    putStrLn prints the string without the quotes of show.

  5. Which package is always in build-depends?

    Answer

    base

    The Prelude and the runtime come from base, so every component depends on it.

  6. What happens when a dependency is not installed and there is no index?

    Answer

    Cabal cannot resolve the dependencies and stops with an error

    The resolver needs the package list, so an unknown package is a resolution error.

  7. What is a common stanza for?

    Answer

    Sharing fields such as ghc-options between components

    A component imports the stanza, so one definition of the flags reaches every component.

  8. What does cabal run mindemo do?

    Answer

    Builds the package if needed and runs its executable

    run builds the executable and executes it with the terminal attached.

  9. What does default-language: Haskell2010 select?

    Answer

    The set of language extensions the modules are compiled with

    It picks the language standard and with it the extensions that are on by default.

  10. What does a second cabal build --offline with no change say?

    Answer

    Up to date

    Cabal compares timestamps and flags, so an unchanged project is not rebuilt.

The code on this page was built with GHC 9.10.3 and cabal-install 3.16.0.0, and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev

Banner image