users-guide: Add discussion of shared object namingwip/T18074

Fixes #18074.

2 files changed, 10 insertions, 1 deletions

diff --git a/docs/users_guide/packages.rst b/docs/users_guide/packages.rst
index fae18241ea..75774c8055 100644
--- a/docs/users_guide/packages.rst
+++ b/docs/users_guide/packages.rst
@@ -1061,6 +1061,14 @@ extra indirection).
    its output in place of ⟨GHCVersion⟩. See also :ref:`options-codegen`
    on how object files must be prepared for shared object linking.
 
+-  When building a shared library, care must be taken to ensure that the
+   resulting object is named appropriately. In particular, GHC expects the
+   name of a shared object to have the form ``libHS<unit id>-ghc<ghc
+   version>.<ext>`` where *unit id* is the unit ID given during compilation via
+   the :ghc-flag:`-this-unit-id ⟨unit-id⟩` flag, *ghc version* is the version of
+   GHC that produced/consumes the object and *ext* is the host system's usual
+   file extension for shared objects.
+
 To compile a module which is to be part of a new package, use the
 ``-package-name`` (to identify the name of the package) and
 ``-library-name`` (to identify the version and the version hashes of its
diff --git a/docs/users_guide/phases.rst b/docs/users_guide/phases.rst
index d0afe80a23..b2664cf180 100644
--- a/docs/users_guide/phases.rst
+++ b/docs/users_guide/phases.rst
@@ -807,7 +807,8 @@ for example).
 
     When creating shared objects for Haskell packages, the shared object
     must be named properly, so that GHC recognizes the shared object
-    when linked against this package. See shared object name mangling.
+    when linking against this package.
+    See :ref:`shared object name mangling <building-packages>` for details.
 
 .. ghc-flag:: -dynload
     :shortdesc: Selects one of a number of modes for finding shared libraries at runtime.