Add documentation

Author: 9999years

changelog.d/pr-8717

@@ -0,0 +1,25 @@
+synopsis: Always pass `ghc-options` to GHC
+packages: Cabal
+prs: #8717
+issues:
+
+description: {
+
+Previously, options set in the package field `ghc-options` would not be passed
+to GHC during the link phase for shared objects (where multiple `.o` or
+`.dyn_o` files are merged into a single object file). This made it impossible
+to use `ghc-options` to use a different linker by setting (for example)
+`ghc-options: -optl-fuse-ld=mold -optlm-fuse-ld=mold`; the options would be
+dropped in the link phase, falling back to the default linker.
+
+It was possible to work around this by duplicating the `ghc-options` to
+`ghc-shared-options`, which _are_ passed in the shared link phase, but that had
+the (undocumented and unfortunate) side-effect of disabling the GHC
+`-dynamic-too` flag, effectively doubling compilation times when
+`ghc-shared-options` are set.
+
+Now, `ghc-options` are combined with `ghc-shared-options` (to accurately
+reflect the documentation on this feature) and the fact that
+`ghc-shared-options` disables `-dynamic-too` is documented.
+
+}

doc/cabal-package.rst

@@ -2045,6 +2045,11 @@ system-dependent values for these fields.
     ones specified via :pkg-field:`ghc-options`, and are passed to GHC during
     both the compile and link phases.
 
+    Note that if any :pkg-field:`ghc-shared-options` are set, the
+    ``-dynamic-too` option will never be passed to GHC, leading to all modules
+    being compiled twice (once to generate the ``.o`` files and another to
+    generate the ``.dyn_o`` files).
+
 .. pkg-field:: ghcjs-options: token list
 
    Like :pkg-field:`ghc-options` but applies to GHCJS