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:
- name and version identify the package and name the build folder.
- common warnings is a stanza that other stanzas import, which is how one set of flags reaches every component.
- build-depends is the dependency list with version bounds, and base is always one of them.
- hs-source-dirs is where the modules are, main-is is the file with main.
- default-language selects the extension set; the lesson on Haskell 2010 and GHC2021 explains what changes.
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:
- base, containers, text, bytestring, array, deepseq, directory, filepath, process, time.
- mtl, transformers, stm, exceptions, parsec, binary.
- unix, template-haskell, pretty, Cabal, hpc and the ghc-* packages.
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
- Create a package with cabal init -n --minimal --exe and change the generated program to print its arguments.
- Add -O2 to the ghc-options of the common stanza and rebuild.
- Run cabal build --offline -v and find the ghc command line Cabal used.
- Find the built executable under dist-newstyle/ and run it without Cabal.
- Add text to the dependencies, use Data.Text in the program and rebuild offline.
- 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.
-
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.
-
What does
cabal build --offlinedo?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.
-
Where do the build artefacts go?
Answer
dist-newstyle/Cabal keeps the objects, interfaces and binaries under dist-newstyle, keyed by package and compiler.
-
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.
-
Which package is always in
build-depends?Answer
baseThe Prelude and the runtime come from base, so every component depends on it.
-
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.
-
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.
-
What does
cabal run mindemodo?Answer
Builds the package if needed and runs its executable
run builds the executable and executes it with the terminal attached.
-
What does
default-language: Haskell2010select?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.
-
What does a second
cabal build --offlinewith no change say?Answer
Up to dateCabal 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