Commit 5b8f95d7 authored by David Feuer's avatar David Feuer Committed by Ben Gamari
Browse files

A few documentation fixes

`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
parent 86466489
......@@ -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
......
......@@ -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`
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment