GnuMP
=====

The http://www.gnu.org/software/gmp/gmp.html[GnuMP] library (GNU
multiprecision library) is a library for arbitrary precision integer
arithmetic.  MLton uses the GnuMP library to implement the
<:BasisLibrary: Basis Library> `IntInf` module.

== Known issues ==

* There is a known problem with the GnuMP library (prior to version
4.2.x), where it requires a lot of stack space for some computations,
e.g. `IntInf.toString` of a million digit number.  If you run with
stack size limited, you may see a segfault in such programs.  This
problem is mentioned in the http://gmplib.org/#FAQ[GnuMP FAQ], where
they describe two solutions.

** Increase (or unlimit) your stack space.  From your program, use
`setrlimit`, or from the shell, use `ulimit`.

** Configure and rebuild `libgmp` with `--disable-alloca`, which will
cause it to allocate temporaries using `malloc` instead of on the
stack.

* On some platforms, the GnuMP library may be configured to use one of
multiple ABIs (Application Binary Interfaces).  For example, on some
32-bit architectures, GnuMP may be configured to represent a limb as
either a 32-bit `long` or as a 64-bit `long long`.  Similarly, GnuMP
may be configured to use specific CPU features.
+
In order to efficiently use the GnuMP library, MLton represents an
`IntInf.int` value in a manner compatible with the GnuMP library's
representation of a limb.  Hence, it is important that MLton and the
GnuMP library agree upon the representation of a limb.

** When using a source package of MLton, building will detect the
GnuMP library's representation of a limb.

** When using a binary package of MLton that is dynamically linked
against the GnuMP library, the build machine and the install machine
must have the GnuMP library configured with the same representation of
a limb.  (On the other hand, the build machine need not have the GnuMP
library configured with CPU features compatible with the install
machine.)

** When using a binary package of MLton that is statically linked
against the GnuMP library, the build machine and the install machine
need not have the GnuMP library configured with the same
representation of a limb.  (On the other hand, the build machine must
have the GnuMP library configured with CPU features compatible with
the install machine.)
+
However, MLton will be configured with the representation of a limb
from the GnuMP library of the build machine.  Executables produced by
MLton will be incompatible with the GnuMP library of the install
machine.  To _reconfigure_ MLton with the representation of a limb
from the GnuMP library of the install machine, one must edit:
+
----
/usr/lib/mlton/self/sizes
----
+
changing the
+
----
mplimb = ??
----
+
entry so that `??` corresponds to the bytes in a limb; and, one must edit:
+
----
/usr/lib/mlton/sml/basis/config/c/arch-os/c-types.sml
----
+
changing the
+
----
(* from "gmp.h" *)
structure C_MPLimb = struct open Word?? type t = word end
functor C_MPLimb_ChooseWordN (A: CHOOSE_WORDN_ARG) = ChooseWordN_Word?? (A)
----
+
entries so that `??` corresponds to the bits in a limb.
