Document GMP build [skip ci]

1 files changed, 80 insertions, 0 deletions

diff --git a/libraries/integer-gmp/README.rst b/libraries/integer-gmp/README.rst
new file mode 100644
index 0000000000..e5f19279d9
--- /dev/null
+++ b/libraries/integer-gmp/README.rst
@@ -0,0 +1,80 @@
+GMP
+===
+
+integer-gmp depends on the external GMP library (gmplib.org). The latter
+provides a header ("gmp.h") and a library to link with.
+
+Linking
+-------
+
+Sadly we can't just put a ``extra-libraries: gmp`` field in the Cabal file because
+``integer-gmp`` is a boot package that is part of GHC's *binary* distribution.
+It means that it won't be rebuilt on each user platform. In particular it can be
+used in an environment that doesn't provide GMP.
+
+A solution would be to always link GMP statically with ``integer-gmp``, but:
+
+1. GMP's license is LPGL while GHC's license is BSD
+
+2. Cabal doesn't provide an easy way to build a Haskell library statically
+   linked with an external library.
+   See https://github.com/haskell/cabal/issues/4042
+
+So, we support the following configurations:
+
+* Dynamically linked GMP
+   * Found in usual library paths
+   * Found in a specified library path
+* Statically linked GMP ("in-tree GMP")
+   * Built by GHC's build system
+
+As Cabal can't statically link an external library with a Haskell library,
+GHC's build system uses a hack:
+   1. it builds libgmp.a
+   2. it extracts the objects (.o) from it
+   3. it passes these objects as "extra" objects when it links integer-gmp
+
+Note that these objects must be built as position independent code (PIC) because
+they end up being used in statically and dynamically linked code (cf #17799).
+
+Configuration
+-------------
+
+GHC's build system provides a ``configure`` script that can be used to setup how
+GMP is linked:
+
+.. code::
+
+  --with-gmp-includes            directory containing gmp.h
+  --with-gmp-libraries           directory containing gmp library
+  --with-intree-gmp              force using the in-tree GMP
+  --with-gmp-framework-preferred on OSX, prefer the GMP framework to the gmp lib
+
+These options are then used when integer-gmp package is configured: in the
+.cabal file, we can see the field ``build-type: Configure``, meaning that the
+``configure`` script in ``libraries/integer-gmp/`` is executed during the setup
+phase of the package.
+
+This script is responsible of creating ``integer-gmp.buildinfo`` (from
+``integer-gmp.buildinfo.in``). The fields contained in this file are
+merged with the ones already defined in ``integer-gmp.cabal``.
+
+See
+https://www.haskell.org/cabal/users-guide/developing-packages.html#system-dependent-parameters.
+
+Headers
+-------
+
+When GMP is statically linked (in-tree build), a user of the integer-gmp package
+can't have access to the "gmp.h" header file. So GHC's build system copies the
+``ghc.h`` header from the in-tree build to ``integer-gmp/include/ghc-gmp.h``. As you
+can see in ``integer-gmp.buildinfo[.in]``, ``ghc-gmp.h`` is installed as a
+header (``install-includes`` field).
+
+While the commit that introduced it (a9a0dd34dcdfb7309f57bda88435acca14ec54d5)
+doesn't document it, it's probably to get access to other GMP functions.
+
+Note that when in-tree GMP build isn't used, ``ghc-gmp.h`` only contains
+``#include <gmp.h>``. Hence it imports the header from the HOST platform, which
+may not be exactly the same as the one used on the BUILD platform to build the
+integer-gmp package.