A few documentation fixes
authorDavid Feuer <david.feuer@gmail.com>
Sat, 20 May 2017 16:56:20 +0000 (12:56 -0400)
committerBen Gamari <ben@smart-cactus.org>
Sat, 20 May 2017 20:29:18 +0000 (16:29 -0400)
`MIN_VERSION_pkg` was documented backwards. An important caveat
about initializing the Haskell runtime was buried in a footnote.
The documentation of `-dynamic` was (even more) confusing.

Reviewers: austin, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

Differential Revision: https://phabricator.haskell.org/D3582

docs/users_guide/bugs.rst
docs/users_guide/ffi-chap.rst
docs/users_guide/phases.rst

index 707f66b..7ccb215 100644 (file)
@@ -342,7 +342,7 @@ The Foreign Function Interface
 ``hs_init()``, ``hs_exit()``
     The FFI spec requires the implementation to support re-initialising
     itself after being shut down with ``hs_exit()``, but GHC does not
-    currently support that.
+    currently support that. See :ghc-ticket:`13693`.
 
     .. index::
         single: hs_init
index d4bf343..35557b8 100644 (file)
@@ -311,8 +311,10 @@ can separate out any arguments for the RTS (i.e. those arguments between
 After we've finished invoking our Haskell functions, we can call
 ``hs_exit()``, which terminates the RTS.
 
-There can be multiple calls to ``hs_init()``, but each one should be
-matched by one (and only one) call to ``hs_exit()`` [1]_.
+There can be multiple calls to ``hs_init()``, but each one should be matched by
+one (and only one) call to ``hs_exit()``. The outermost ``hs_exit()`` will
+actually de-initialise the system.  Note that currently GHC's runtime cannot
+reliably re-initialise after this has happened; see :ref:`infelicities-ffi`.
 
 .. note::
     When linking the final program, it is normally easiest to do the
@@ -320,11 +322,6 @@ matched by one (and only one) call to ``hs_exit()`` [1]_.
     don't forget the flag :ghc-flag:`-no-hs-main`, otherwise GHC
     will try to link to the ``Main`` Haskell module.
 
-.. [1]
-   The outermost ``hs_exit()`` will actually de-initialise the system.
-   Note that currently GHC's runtime cannot reliably re-initialise after
-   this has happened, see :ref:`infelicities-ffi`.
-
 To use ``+RTS`` flags with ``hs_init()``, we have to modify the example
 slightly. By default, GHC's RTS will only accept "safe" ``+RTS`` flags
 (see :ref:`options-linker`), and the :ghc-flag:`-rtsopts`
index 6bc9767..1efe6a4 100644 (file)
@@ -324,7 +324,7 @@ defined by your local GHC installation, the following trick is useful:
     This macro is available starting GHC 8.0.  It is defined for every
     exposed package. This macro is provided for convenience to write CPP
     conditionals testing if a package version is ``x.y.z`` or
-    less.  It is identical in behavior to the ``MIN_VERSION_pkgname``
+    later.  It is identical in behavior to the ``MIN_VERSION_pkgname``
     macros that Cabal defines.
 
 .. _cpp-string-gaps:
@@ -459,7 +459,11 @@ Options affecting code generation
     :noindex:
 
     When generating code, assume that entities imported from a different
-    package will reside in a different shared library or binary.
+    package will be dynamically linked. This can reduce code size
+    tremendously, but may slow-down cross-package calls of non-inlined
+    functions. There can be some complications combining :ghc-flag:`-shared`
+    with this flag relating to linking in the RTS under Linux. See
+    :ghc-ticket:`10352`.
 
     Note that using this option when linking causes GHC to link against
     shared libraries.