Merge pull request #12103 from haskell/mergify/bp/3.18/pr-12022

Backport #12022: Re #11498 Better document Cabal's --semaphore=SEMAPHORE option

Author: mergify[bot]

Cabal/src/Distribution/Simple/Setup/Build.hs

@@ -152,7 +152,7 @@ buildOptions progDb showOrParseArgs =
     , option
         []
         ["semaphore"]
-        "Use the specified semaphore so GHC can compile components in parallel"
+        "Use the specified semaphore identifier so GHC can compile components in parallel"
         buildUseSemaphore
         (\v flags -> flags{buildUseSemaphore = v})
         (reqArg' "SEMAPHORE" Flag flagToList)

changelog.d/pr-12022.md

@@ -0,0 +1,10 @@
+synopsis: Better document Cabal's `--semaphore=SEMAPHORE` option in light of `semaphore-compat-2.0.0`
+packages: Cabal
+prs: #12022
+significance:
+
+description: {
+
+- Cabal's `--semaphore=SEMAPHORE` option is better documented in the user's guide and in `--help`.
+
+}

doc/setup-commands.rst

@@ -1089,13 +1089,22 @@ This command takes the following options:
 
     :since: 3.12.0.0
 
+    This option causes Cabal to control parallelism by using the specified
+    semaphore.
+
     GHC 9.8.1 and later can act as a jobserver client, which enables two or more
     GHC processes running at once to share system resources with each other,
-    communicating via a specified system semaphore. The system semaphore is
-    identified by a name (a string).
+    communicating via a semaphore.
 
-    This option causes Cabal to control parallelism by using the specified
-    system semaphore.
+    The expected use is that the system controlling the build (e.g.
+    ``cabal-install``, ``stack``, ``nix`` or ``buck2``) (a jobserver) creates or
+    obtains a semaphore using the ``semaphore-compat`` library. It then passes
+    the semaphore to jobserver clients in order to control the amount of
+    parallelism. This is done by passing the corresponding semaphore identifier
+    to Cabal via the ``--semaphore`` option.
+
+    For more information, see
+    `semaphore-compat <https://hackage.haskell.org/package/semaphore-compat>`_.
 
 .. _setup-haddock: