Label semaphore feature as experimental

Author: mpilgrem

ChangeLog.md

@@ -12,9 +12,11 @@ Behavior changes:
 
 Other enhancements:
 
-* Add flag `--[no-]semaphore` (default: disabled) to Stack's `build` command,
-  to allow GHC to use a system semaphore to perform compilation in parallel when
-  possible. Supported, by default, by GHC 9.10.1 or later.
+* Experimental: Add flag `--[no-]semaphore` (default: disabled) to Stack's
+  `build` command, to allow GHC to use a system semaphore to perform compilation
+  in parallel when possible. Supported, by default, by GHC 9.10.1 or later. The
+  option is considered experiemental because, on Linux only, musl and non-musl
+  semaphores are incompatible.
 
 Bug fixes:
 

doc/commands/build_command.md

@@ -919,6 +919,8 @@ the [`stack path --local-install-root`](path_command.md) command.
 
 ### `--[no]-semaphore` flag
 
+:octicons-beaker-24: Experimental
+
 :octicons-tag-24: UNRELEASED
 
 Default: Disabled
@@ -934,6 +936,13 @@ parallel when possible.
     Cabal 3.12.0.0 (a boot package of GHC 9.10.1) and later. The flag is ignored
     with a warning when the feature is unsupported.
 
+!!! warning
+
+    On Linux, musl and non-musl system semaphores are incompatible. That means
+    that a Stack executable built on Alpine Linux (such as the official Stack
+    for Linux) creates system semaphores that cannot be used by a GHC executable
+    built on non-musl Linux distributions.
+
 ### `--[no-]split-objs` flag
 
 :octicons-beaker-24: Experimental

doc/configure/yaml/non-project.md

@@ -157,9 +157,9 @@ Default:
 
 ~~~yaml
 build:
-  # Since Stack UNRELEASED. Supported by GHC 9.8.1 or later with Cabal 3.12.0.0
-  # (a boot package of GHC 9.10.1) or later. Ignored with a warning when
-  # unsupported.
+  # Experimental. Since Stack UNRELEASED. Supported by GHC 9.8.1 or later with
+  # Cabal 3.12.0.0 (a boot package of GHC 9.10.1) or later. Ignored with a
+  # warning when unsupported.
   semaphore: false
 
   library-profiling: false