add -flink-rts flag to link the rts when linking a shared or static library #18072

By default we don't link the RTS when linking shared libraries because in the
most usual mode a shared library is an intermediary product, for example a
Haskell library, that will be linked into some executable in the end. So we
wish to defer the RTS flavour to link to the final link.

However sometimes the final product is the shared library, for example when
writing a plugin for some other system, so we do wish the shared library to
link the RTS.

For consistency we also make -staticlib honor this flag and its inversion.
-staticlib currently implies -flink-shared.

3 files changed, 36 insertions, 7 deletions

diff --git a/docs/users_guide/8.12.1-notes.rst b/docs/users_guide/8.12.1-notes.rst
index 1eb577c36e..b7f0444d69 100644
--- a/docs/users_guide/8.12.1-notes.rst
+++ b/docs/users_guide/8.12.1-notes.rst
@@ -216,6 +216,9 @@ Language
 Compiler
 ~~~~~~~~
 
+- A new flag :ghc-flag:`-flink-rts` to enable linking the RTS when linking
+  shared libraries.
+
 
 GHCi
 ~~~~
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index 5975962370..c7a17f6475 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -735,6 +735,8 @@ for example).
     :type: dynamic
     :category: linking
 
+    :implies: :ghc-flag:`-flink-rts`
+
     Link all passed files into a static library suitable for linking.
     To control the name, use the :ghc-flag:`-o ⟨file⟩` option
     as usual. The default name is ``liba.a``.
@@ -826,6 +828,23 @@ for example).
     libraries at runtime. See :ref:`finding-shared-libs` for a
     description of each mode.
 
+.. ghc-flag:: -flink-rts
+    :shortdesc: Link the runtime when generating a shared or static library
+    :type: dynamic
+    :category: linking
+
+    When linking shared libraries (:ghc-flag:`-shared`) GHC does not
+    automatically link the RTS.  This is to allow choosing the RTS flavour
+    (:ghc-flag:`-threaded`, :ghc-flag:`-eventlog`, etc) when linking an
+    executable. 
+    However when the shared library is the intended product it is useful to be
+    able to reverse this default. See :ref:`shared-libraries-c-api` for an
+    usage example.
+
+    When linking a static library (:ghc-flag:`-staticlib`) GHC links the RTS
+    automatically, you can reverse this behaviour by reversing this flag:
+    ``-fno-link-rts``.
+
 .. ghc-flag:: -main-is ⟨thing⟩
     :shortdesc: Set main module and function
     :type: dynamic
diff --git a/docs/users_guide/shared_libs.rst b/docs/users_guide/shared_libs.rst
index 7e525019ca..4c9ad621f7 100644
--- a/docs/users_guide/shared_libs.rst
+++ b/docs/users_guide/shared_libs.rst
@@ -92,6 +92,8 @@ files to use the extension ``.dyn_hi``. The other requirements are the
 same as for C libraries and are described below, in particular the use
 of the flags :ghc-flag:`-dynamic`, :ghc-flag:`-fPIC` and :ghc-flag:`-shared`.
 
+.. _shared-libraries-c-api:
+
 Shared libraries that export a C API
 ------------------------------------
 
@@ -115,19 +117,24 @@ the :ghc-flag:`-dynamic`, :ghc-flag:`-fPIC` and :ghc-flag:`-shared` flags:
 
 .. code-block:: none
 
-    ghc --make -dynamic -shared -fPIC Foo.hs -o libfoo.so
+    ghc --make -dynamic -shared -fPIC -flink-rts Foo.hs -o libfoo.so
 
 As before, the :ghc-flag:`-dynamic` flag specifies that this library links
-against the shared library versions of the ``rts`` and ``base`` package. The
-:ghc-flag:`-fPIC` flag is required for all code that will end up in a shared
-library. The :ghc-flag:`-shared` flag specifies to make a shared library rather
-than a program. To make this clearer we can break this down into separate
-compilation and link steps:
+against the shared library versions of the ``base`` package.
+:ghc-flag:`-flink-rts` additionally links against the shared library version of
+the ``rts`` package (linking against the ``rts`` package is not enabled by
+default when building shared libraries). You may also omit ``-flink-rts``
+and link the RTS library into your final executable.
+
+The :ghc-flag:`-fPIC` flag is required for all code that will end up in a
+shared library. The :ghc-flag:`-shared` flag specifies to make a shared library
+rather than a program. To make this clearer we can break this down into
+separate compilation and link steps:
 
 .. code-block:: none
 
     ghc -dynamic -fPIC -c Foo.hs
-    ghc -dynamic -shared Foo.o -o libfoo.so
+    ghc -dynamic -shared -flink-rts Foo.o -o libfoo.so
 
 In principle you can use :ghc-flag:`-shared` without :ghc-flag:`-dynamic` in the
 link step. That means to statically link the runtime system and all of the base