Add --semaphore

[horriblename]

implements #6131

Please include the following checklist in your pull request:

• Any changes that could be relevant to users have been recorded in ChangeLog.md.
• The documentation has been updated, if necessary

Please also shortly describe how you tested your change. Bonus points for added tests!

(I'm not sure what kind of test I can add for this?)

a quick benchmark matches claims in https://well-typed.com/blog/2023/08/reducing-haskell-parallel-build-times/ regarding compiling lens (112s vs 140s, ~20% improvement).

$ time stack exec -- stack build --work-dir .temp-work lens
  298.37s user 43.14s system 242% cpu 2:20.69 total

# with --semaphore
$ time stack exec -- stack build --semaphore --work-dir .temp-work lens
  349.93s user 47.79s system 353% cpu 1:52.50 total

rm -r $(stack exec -- stack path --snapshot-pkg-db) was deleted before each run

Some notes about the implementation

• this uses semaphore-compat, which is also used by cabal

[horriblename]

probably better if I can refer to cabal's docs for the --semaphore flag, but I couldn't find any (aside from the extremely short description in --help). There are some docs for cabal-install's --semaphore but that's not quite the same thing

[mpilgrem]

@horriblename, thanks! Don't worry about the CI for Linux with --alpine (that is waiting for Stack 3.9.3 to appear in Docker images).

I am wondering about the user experience if they accidently specify --semaphore when building with GHC < 9.8.

EDIT: --semaphore appears to have been introduced with Cabal-3.12.0.0, which was a boot package of GHC 9.10.1.

I had not paid attention to --semaphore, as the Cabal project has not yet documented its existence. However, I see that stack runghc -- Setup.hs build --help offers up the (largely unhelpful):

Flags for build:
...
--semaphore=SEMAPHORE          semaphore

I have opened an issue at Cabal's repository:

• No documentation for Cabal's --semaphore haskell/cabal#11498

[mpilgrem]

@horriblename, other than handling the Stack user experience when --semaphore=SEMAPHORE is not supported by Cabal, this looks good to me.

I've pushed a commit to better conform the online and in-app documentation to other documentation.

EDIT: I have also pushed a commit to ignore the flag with a warning when it is unsupported.

EDIT2: I have also pushed a commit to update a relevant unit test.

[mpilgrem]

Tested on Windows 11 by building Stack itself: reduced from 83 s to 50 s (~40% less time).

[horriblename]

EDIT: I have also pushed a commit to ignore the flag with a warning when it is unsupported.

I suppose there's nothing I need to do anymore? (thanks!)

[mpilgrem]

@horriblename, many thanks. I'll likely merge this once the current CI passes.

[mpilgrem]

@horriblename, some disappointing news. I have learned that GHC's semaphore feature has major problems on Linux, because musl and non-musl semaphores are incompatible:

• https://discourse.haskell.org/t/well-typed-blog-reducing-haskell-parallel-build-times-using-semaphores/7211
• [Ubuntu] [3.12.0.0-prerelease] Semaphore does not exist haskell/cabal#9993
• https://gitlab.haskell.org/ghc/ghc/-/issues/25087
• Update jsem proposal to address problems discovered in GHC #25087 (under review) ghc-proposals/ghc-proposals#673

In the light of that, I am going to add something to Stack's documentation and label the feature as experimental.