A library, an executable and a test suite

One package, three components

A package that is more than a script has a library with the code, an executable that is a thin wrapper around it, and a test suite that exercises the library without the program. Cabal calls the three components of the package, and each has its own stanza in the .cabal file and its own build folder under dist-newstyle/.

shop/ ├── shop.cabal ├── src/Shop/Price.hs ├── app/Main.hs └── test/Spec.hs

The split is what makes the test suite cheap: it depends on the library and not on the executable, so it does not run the program to check a function. The next lesson runs this suite and breaks it on purpose; this one builds it.

The .cabal file

cabal-version: 3.0 name: shop version: 0.1.0.0 build-type: Simple library exposed-modules: Shop.Price hs-source-dirs: src build-depends: base default-language: Haskell2010 executable shop main-is: Main.hs hs-source-dirs: app build-depends: base, shop default-language: Haskell2010 test-suite shop-test type: exitcode-stdio-1.0 main-is: Spec.hs hs-source-dirs: test build-depends: base, shop default-language: Haskell2010

Three details carry the structure:

The library module

The module does the work: a price with tax and a string for pence. It imports nothing beyond base and exports two functions:

module Shop.Price (withTax, formatPence) where withTax :: Int -> Int withTax pence = pence + pence `div` 5 formatPence :: Int -> String formatPence pence = show (pence `div` 100) ++ "." ++ pad (show (pence `mod` 100)) where pad [d] = ['0', d] pad ds = ds

The path is src/Shop/Price.hs because the module is Shop.Price, and hs-source-dirs: src is what makes the compiler look under src/.

The executable

module Main (main) where import Shop.Price (formatPence, withTax) main :: IO () main = mapM_ (putStrLn . formatPence . withTax) [100, 250, 999]

The program is a composition and a loop: three prices go through the tax and the formatter and come out as three lines. All the arithmetic is in the library, which is what the test suite checks.

The test suite

An exitcode-stdio-1.0 suite is a program with a main whose exit status is the verdict. This one prints a line per check and exits with 1 if any of them failed:

module Main (main) where import Shop.Price (formatPence, withTax) import System.Exit (exitFailure, exitSuccess) check :: String -> Bool -> IO Bool check label ok = do putStrLn ((if ok then "ok " else "FAIL ") ++ label) pure ok main :: IO () main = do results <- sequence [ check "100 with tax" (withTax 100 == 120) , check "format 120" (formatPence 120 == "1.20") , check "format 5" (formatPence 5 == "0.05") ] if and results then exitSuccess else exitFailure

sequence runs the three checks in order and collects the booleans, and and decides the exit. The ok column is padded to five characters so the failures line up with the successes, the same trick the formatting lesson used with printf.

build, run and test

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):
 - shop-0.1.0.0 (lib) (first run)
 - shop-0.1.0.0 (exe:shop) (first run)
Configuring library for shop-0.1.0.0...
Preprocessing library for shop-0.1.0.0...
Building library for shop-0.1.0.0...
[1 of 1] Compiling Shop.Price ( src/Shop/Price.hs, dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/build/Shop/Price.o, dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/build/Shop/Price.dyn_o )
Configuring executable 'shop' for shop-0.1.0.0...
Preprocessing executable 'shop' for shop-0.1.0.0...
Building executable 'shop' for shop-0.1.0.0...
[1 of 1] Compiling Main ( app/Main.hs, dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/x/shop/build/shop/shop-tmp/Main.o )
[2 of 2] Linking dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/x/shop/build/shop/shop

The library is built once and both other components compile against it, so the shared code is not compiled three times. The test suite is not part of build: Cabal builds it when test asks for it.

cabal run --offline shop

1.20
3.00
11.98

100 pence with tax is 120 and prints as 1.20, and 999 pence is 1198, which is 11.98. The numbers are the library's answer, not the program's, which is why the suite below can check them without starting the executable.

cabal test --offline

Build profile: -w ghc-9.10.3 -O1
In order, the following will be built (use -v for more details):
 - shop-0.1.0.0 (test:shop-test) (first run)
Configuring test suite 'shop-test' for shop-0.1.0.0...
Preprocessing test suite 'shop-test' for shop-0.1.0.0...
Building test suite 'shop-test' for shop-0.1.0.0...
[1 of 1] Compiling Main ( test/Spec.hs, dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/t/shop-test/build/shop-test/shop-test-tmp/Main.o )
[2 of 2] Linking dist-newstyle/build/x86_64-linux/ghc-9.10.3/shop-0.1.0.0/t/shop-test/build/shop-test/shop-test
Running 1 test suites...
Test suite shop-test: RUNNING...
ok 100 with tax
ok format 120
ok format 5
Test suite shop-test: PASS
1 of 1 test suites (1 of 1 test cases) passed.

Between the PASS line and the last line Cabal prints the absolute path of the log file under dist-newstyle/; it is left out here because it depends on where the project sits. The suite prints its three lines because Cabal runs it with the terminal attached, and the PASS is Cabal's reading of the exit status, not the suite's own words. The next lesson makes a check fail and shows what Cabal does then.

Exercises

  1. Add a formatPence case for a negative amount and a check for it in the suite.
  2. Add a second module to the library and list it in exposed-modules.
  3. Move the test driver into a module of its own under test/ and list it in other-modules.
  4. Change build-depends: base to base, containers and use a Map in the library.
  5. Run cabal test --offline twice and explain the second run.
  6. Explain why the test suite depends on the library and not on the executable.

Questions

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

  1. What are the three components of the package in this lesson?

    Answer

    A library, an executable and a test suite

    The .cabal file has a library, executable and test-suite stanza.

  2. What does exposed-modules list?

    Answer

    The modules another package may import

    Only the exposed modules are part of the public interface of the library.

  3. What does type: exitcode-stdio-1.0 mean for a test suite?

    Answer

    The suite is a program whose exit status is the verdict

    This interface runs the suite as a program and reads its exit status.

  4. What does this program print? module Main (main) where main :: IO () main = print (sum [1, 2, 3 :: Int])

    Answer

    6

    The sum of the three numbers is printed by print as 6.

  5. Why does the test suite depend on shop as well as base?

    Answer

    It imports the library module of the package

    The suite imports Shop.Price, which is the library component named shop.

  6. What does this program print? module Main (main) where import System.Exit (exitSuccess) main :: IO () main = do putStrLn "done" exitSuccess

    Answer

    done

    The line is printed and exitSuccess then ends the program with status 0.

  7. When does Cabal build the test suite?

    Answer

    When a command such as cabal test asks for it

    build builds the library and executables; test builds and runs the suite.

  8. What does this program print? module Main (main) where check :: Bool -> Bool check ok = ok main :: IO () main = putStrLn (if and (map check [True, True]) then "all ok" else "failures")

    Answer

    all ok

    Both checks are True, so and gives True and the first branch is printed.

  9. Where do the library and the executable find their sources?

    Answer

    In the folders given by hs-source-dirs, here src and app

    Each component declares its own hs-source-dirs, which is how src and app stay separate.

  10. What does the PASS line of cabal test report?

    Answer

    The exit status of the suite program

    Cabal reads the exit status of the exitcode-stdio suite and reports it as PASS or FAIL.

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