[Git][ghc/ghc][wip/T18074] users-guide: Add discussion of shared object naming

[Ben Gamari]

Ben Gamari pushed to branch wip/T18074 at Glasgow Haskell Compiler / GHC


Commits:
df3a7950 by Ben Gamari at 2020-05-10T15:16:58-04:00
users-guide: Add discussion of shared object naming

Fixes #18074.

- - - - -


2 changed files:

- docs/users_guide/packages.rst
- docs/users_guide/phases.rst


Changes:

=====================================
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


=====================================
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.



View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/df3a7950f10ea2247707b3789e6fdfe301726343

-- 
View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/df3a7950f10ea2247707b3789e6fdfe301726343
You're receiving this email because of your account on gitlab.haskell.org.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.haskell.org/pipermail/ghc-commits/attachments/20200510/1e7ca86a/attachment-0001.html>