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

[philderbeast]

What is wrong with the docs?
The docs for 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

[philderbeast]

-jsem completely overrides any earlier -jN or -jsem ; and vice versa.
SOURCE: ghc-proposals/ghc-proposals#540 (comment)

Could we update the docs to say how -j and --semaphore interact in a bit more detail?

The cabal docs say about --semaphore that "This option instructs cabal to control parallelism by creating a new system semaphore, whose number of tokens is specified by --jobs (or -j)."