doc/guide/src/GnuMP.adoc

   1 GnuMP
   2 =====
   3
   4 The http://gmplib.org[GnuMP] library (GNU Multiple Precision
   5 arithmetic library) is a library for arbitrary precision integer
   6 arithmetic.  MLton uses the GnuMP library to implement the
   7 <:BasisLibrary: Basis Library> `IntInf` module.
   8
   9 == Known issues ==
  10
  11 * There is a known problem with the GnuMP library (prior to version
  12 4.2.x), where it requires a lot of stack space for some computations,
  13 e.g. `IntInf.toString` of a million digit number.  If you run with
  14 stack size limited, you may see a segfault in such programs.  This
  15 problem is mentioned in the http://gmplib.org/#FAQ[GnuMP FAQ], where
  16 they describe two solutions.
  17
  18 ** Increase (or unlimit) your stack space.  From your program, use
  19 `setrlimit`, or from the shell, use `ulimit`.
  20
  21 ** Configure and rebuild `libgmp` with `--disable-alloca`, which will
  22 cause it to allocate temporaries using `malloc` instead of on the
  23 stack.
  24
  25 * On some platforms, the GnuMP library may be configured to use one of
  26 multiple ABIs (Application Binary Interfaces).  For example, on some
  27 32-bit architectures, GnuMP may be configured to represent a limb as
  28 either a 32-bit `long` or as a 64-bit `long long`.  Similarly, GnuMP
  29 may be configured to use specific CPU features.
  30 +
  31 In order to efficiently use the GnuMP library, MLton represents an
  32 `IntInf.int` value in a manner compatible with the GnuMP library's
  33 representation of a limb.  Hence, it is important that MLton and the
  34 GnuMP library agree upon the representation of a limb.
  35
  36 ** When using a source package of MLton, building will detect the
  37 GnuMP library's representation of a limb.
  38
  39 ** When using a binary package of MLton that is dynamically linked
  40 against the GnuMP library, the build machine and the install machine
  41 must have the GnuMP library configured with the same representation of
  42 a limb.  (On the other hand, the build machine need not have the GnuMP
  43 library configured with CPU features compatible with the install
  44 machine.)
  45
  46 ** When using a binary package of MLton that is statically linked
  47 against the GnuMP library, the build machine and the install machine
  48 need not have the GnuMP library configured with the same
  49 representation of a limb.  (On the other hand, the build machine must
  50 have the GnuMP library configured with CPU features compatible with
  51 the install machine.)
  52 +
  53 However, MLton will be configured with the representation of a limb
  54 from the GnuMP library of the build machine.  Executables produced by
  55 MLton will be incompatible with the GnuMP library of the install
  56 machine.  To _reconfigure_ MLton with the representation of a limb
  57 from the GnuMP library of the install machine, one must edit:
  58 +
  59 ----
  60 /usr/lib/mlton/self/sizes
  61 ----
  62 +
  63 changing the
  64 +
  65 ----
  66 mplimb = ??
  67 ----
  68 +
  69 entry so that `??` corresponds to the bytes in a limb; and, one must edit:
  70 +
  71 ----
  72 /usr/lib/mlton/sml/basis/config/c/arch-os/c-types.sml
  73 ----
  74 +
  75 changing the
  76 +
  77 ----
  78 (* from "gmp.h" *)
  79 structure C_MPLimb = struct open Word?? type t = word end
  80 functor C_MPLimb_ChooseWordN (A: CHOOSE_WORDN_ARG) = ChooseWordN_Word?? (A)
  81 ----
  82 +
  83 entries so that `??` corresponds to the bits in a limb.