haskell / haskell/cabal

Document `-j` with and without `--semaphore`

Open
#11,467 2 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Haskell
Stars
1.7k
Forks
750
Avg merge
4d 3h
Merged PRs (30d)
28

Description

**What is wrong with the docs?**
The docs for [`jobs`](https://cabal.readthedocs.io/en/latest/cabal-project-description-file.html#cfg-field-jobs) say that "Package building is often quite parallel, so turning on parallelism can speed up build times quite a bit!". I saw no difference with `cabal build` times by adding `-j` (when `-j` is equivalent to `--jobs=$ncpus`). What did make a big difference was also adding `--semaphore`. Could we update the docs accordingly?

Why is the combination of `-j` and `--semaphore` not the default?

**Additional context**

Timing runs with a `cabal clean` before each run.

```
$ cabal --numeric-version
3.17.0.0

$ ghc --numeric-version
9.12.2

$ nproc
24

$ sb_release -a
...
Distributor ID: Ubuntu
Description: Ubuntu 25.10
Release: 25.10
Codename: questing
```

- Timing `cabal`

```
$ time cabal build all --enable-tests --enable-benchmarks
...
________________________________________________________
Executed in 172.14 secs fish external
usr time 250.08 secs 0.40 millis 250.08 secs
sys time 17.20 secs 1.28 millis 17.20 secs
```

```
$ time cabal build all -j --enable-tests --enable-benchmarks
...
________________________________________________________
Executed in 174.24 secs fish external
usr time 252.38 secs 43.69 millis 252.33 secs
sys time 17.18 secs 15.74 millis 17.17 secs
```

```
$ time cabal build all -j --semaphore --enable-tests --enable-benchmarks
...
________________________________________________________
Executed in 110.47 secs fish external
usr time 296.06 secs 0.13 millis 296.06 secs
sys time 18.46 secs 1.06 millis 18.46 secs
```

- Timing `liquid-fixpoint`

```
$ time cabal build all --enable-tests --enable-benchmarks
...
________________________________________________________
Executed in 86.28 secs fish external
usr time 87.78 secs 1.17 millis 87.78 secs
sys time 2.41 secs 0.76 millis 2.41 secs
```

```
$ time cabal build all -j --enable-tests --enable-benchmarks
...
________________________________________________________
Executed in 86.32 secs fish external
usr time 87.61 secs 0.58 millis 87.61 secs
sys time 2.61 secs 1.25 millis 2.61 secs
```

```
$ time cabal build all -j --semaphore --enable-tests --enable-benchmarks
...
________________________________________________________
Executed in 61.66 secs fish external
usr time 105.29 secs 1.95 millis 105.29 secs
sys time 2.81 secs 0.88 millis 2.80 secs
```

Contributor guide

Open the contributing guide

Research direction

Start with the linked `jobs` section in cabal-project-description-file.html and inspect the documentation and command entry points for `-j`/`--jobs` and `--semaphore`. Use the reported `cabal build` timings as context; done means the docs describe their effects and address why the combination is not the default.

Written by the indexing model from the issue text.

Assessment

Tech stack
haskell
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.