Document `-j` with and without `--semaphore`
- 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
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