[hcoop/debian/mlton.git] / doc / guide / localhost / GnuMP

<!DOCTYPE html>\r
<html lang="en">\r
<head>\r
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\r
<meta name="generator" content="AsciiDoc 8.6.9">\r
<title>GnuMP</title>\r
<link rel="stylesheet" href="./asciidoc.css" type="text/css">\r
<link rel="stylesheet" href="./pygments.css" type="text/css">\r
\r
\r
<script type="text/javascript" src="./asciidoc.js"></script>\r
<script type="text/javascript">\r
/*<![CDATA[*/\r
asciidoc.install();\r
/*]]>*/\r
</script>\r
<link rel="stylesheet" href="./mlton.css" type="text/css">\r
</head>\r
<body class="article">\r
<div id="banner">\r
<div id="banner-home">\r
<a href="./Home">MLton 20180207</a>\r
</div>\r
</div>\r
<div id="header">\r
<h1>GnuMP</h1>\r
</div>\r
<div id="content">\r
<div id="preamble">\r
<div class="sectionbody">\r
<div class="paragraph"><p>The <a href="http://gmplib.org">GnuMP</a> library (GNU Multiple Precision\r
arithmetic library) is a library for arbitrary precision integer\r
arithmetic.  MLton uses the GnuMP library to implement the\r
<a href="BasisLibrary"> Basis Library</a> <span class="monospaced">IntInf</span> module.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_known_issues">Known issues</h2>\r
<div class="sectionbody">\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
There is a known problem with the GnuMP library (prior to version\r
4.2.x), where it requires a lot of stack space for some computations,\r
e.g. <span class="monospaced">IntInf.toString</span> of a million digit number.  If you run with\r
stack size limited, you may see a segfault in such programs.  This\r
problem is mentioned in the <a href="http://gmplib.org/#FAQ">GnuMP FAQ</a>, where\r
they describe two solutions.\r
</p>\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
Increase (or unlimit) your stack space.  From your program, use\r
<span class="monospaced">setrlimit</span>, or from the shell, use <span class="monospaced">ulimit</span>.\r
</p>\r
</li>\r
<li>\r
<p>\r
Configure and rebuild <span class="monospaced">libgmp</span> with <span class="monospaced">--disable-alloca</span>, which will\r
cause it to allocate temporaries using <span class="monospaced">malloc</span> instead of on the\r
stack.\r
</p>\r
</li>\r
</ul></div>\r
</li>\r
<li>\r
<p>\r
On some platforms, the GnuMP library may be configured to use one of\r
multiple ABIs (Application Binary Interfaces).  For example, on some\r
32-bit architectures, GnuMP may be configured to represent a limb as\r
either a 32-bit <span class="monospaced">long</span> or as a 64-bit <span class="monospaced">long long</span>.  Similarly, GnuMP\r
may be configured to use specific CPU features.\r
</p>\r
<div class="paragraph"><p>In order to efficiently use the GnuMP library, MLton represents an\r
<span class="monospaced">IntInf.int</span> value in a manner compatible with the GnuMP library&#8217;s\r
representation of a limb.  Hence, it is important that MLton and the\r
GnuMP library agree upon the representation of a limb.</p></div>\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
When using a source package of MLton, building will detect the\r
GnuMP library&#8217;s representation of a limb.\r
</p>\r
</li>\r
<li>\r
<p>\r
When using a binary package of MLton that is dynamically linked\r
against the GnuMP library, the build machine and the install machine\r
must have the GnuMP library configured with the same representation of\r
a limb.  (On the other hand, the build machine need not have the GnuMP\r
library configured with CPU features compatible with the install\r
machine.)\r
</p>\r
</li>\r
<li>\r
<p>\r
When using a binary package of MLton that is statically linked\r
against the GnuMP library, the build machine and the install machine\r
need not have the GnuMP library configured with the same\r
representation of a limb.  (On the other hand, the build machine must\r
have the GnuMP library configured with CPU features compatible with\r
the install machine.)\r
</p>\r
<div class="paragraph"><p>However, MLton will be configured with the representation of a limb\r
from the GnuMP library of the build machine.  Executables produced by\r
MLton will be incompatible with the GnuMP library of the install\r
machine.  To <em>reconfigure</em> MLton with the representation of a limb\r
from the GnuMP library of the install machine, one must edit:</p></div>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>/usr/lib/mlton/self/sizes</pre>\r
</div></div>\r
<div class="paragraph"><p>changing the</p></div>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>mplimb = ??</pre>\r
</div></div>\r
<div class="paragraph"><p>entry so that <span class="monospaced">??</span> corresponds to the bytes in a limb; and, one must edit:</p></div>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>/usr/lib/mlton/sml/basis/config/c/arch-os/c-types.sml</pre>\r
</div></div>\r
<div class="paragraph"><p>changing the</p></div>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>(* from "gmp.h" *)\r
structure C_MPLimb = struct open Word?? type t = word end\r
functor C_MPLimb_ChooseWordN (A: CHOOSE_WORDN_ARG) = ChooseWordN_Word?? (A)</pre>\r
</div></div>\r
<div class="paragraph"><p>entries so that <span class="monospaced">??</span> corresponds to the bits in a limb.</p></div>\r
</li>\r
</ul></div>\r
</li>\r
</ul></div>\r
</div>\r
</div>\r
</div>\r
<div id="footnotes"><hr></div>\r
<div id="footer">\r
<div id="footer-text">\r
</div>\r
<div id="footer-badges">\r
</div>\r
</div>\r
</body>\r
</html>\r
Commit	Line	Data
7f918cf1 CE	1	<!DOCTYPE html>\r
	2	<html lang="en">\r
	3	<head>\r
	4	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">\r
	5	<meta name="generator" content="AsciiDoc 8.6.9">\r
	6	<title>GnuMP</title>\r
	7	<link rel="stylesheet" href="./asciidoc.css" type="text/css">\r
	8	<link rel="stylesheet" href="./pygments.css" type="text/css">\r
	9	\r
	10	\r
	11	<script type="text/javascript" src="./asciidoc.js"></script>\r
	12	<script type="text/javascript">\r
	13	/<![CDATA[/\r
	14	asciidoc.install();\r
	15	/]]>/\r
	16	</script>\r
	17	<link rel="stylesheet" href="./mlton.css" type="text/css">\r
	18	</head>\r
	19	<body class="article">\r
	20	<div id="banner">\r
	21	<div id="banner-home">\r
	22	<a href="./Home">MLton 20180207</a>\r
	23	</div>\r
	24	</div>\r
	25	<div id="header">\r
	26	<h1>GnuMP</h1>\r
	27	</div>\r
	28	<div id="content">\r
	29	<div id="preamble">\r
	30	<div class="sectionbody">\r
	31	<div class="paragraph"><p>The <a href="http://gmplib.org">GnuMP</a> library (GNU Multiple Precision\r
	32	arithmetic library) is a library for arbitrary precision integer\r
	33	arithmetic. MLton uses the GnuMP library to implement the\r
	34	<a href="BasisLibrary"> Basis Library</a> <span class="monospaced">IntInf</span> module.</p></div>\r
	35	</div>\r
	36	</div>\r
	37	<div class="sect1">\r
	38	<h2 id="_known_issues">Known issues</h2>\r
	39	<div class="sectionbody">\r
	40	<div class="ulist"><ul>\r
	41	<li>\r
	42	<p>\r
	43	There is a known problem with the GnuMP library (prior to version\r
	44	4.2.x), where it requires a lot of stack space for some computations,\r
	45	e.g. <span class="monospaced">IntInf.toString</span> of a million digit number. If you run with\r
	46	stack size limited, you may see a segfault in such programs. This\r
	47	problem is mentioned in the <a href="http://gmplib.org/#FAQ">GnuMP FAQ</a>, where\r
	48	they describe two solutions.\r
	49	</p>\r
	50	<div class="ulist"><ul>\r
	51	<li>\r
	52	<p>\r
	53	Increase (or unlimit) your stack space. From your program, use\r
	54	<span class="monospaced">setrlimit</span>, or from the shell, use <span class="monospaced">ulimit</span>.\r
	55	</p>\r
	56	</li>\r
	57	<li>\r
	58	<p>\r
	59	Configure and rebuild <span class="monospaced">libgmp</span> with <span class="monospaced">--disable-alloca</span>, which will\r
	60	cause it to allocate temporaries using <span class="monospaced">malloc</span> instead of on the\r
	61	stack.\r
	62	</p>\r
	63	</li>\r
	64	</ul></div>\r
65	</li>\r
66	<li>\r
67	<p>\r
68	On some platforms, the GnuMP library may be configured to use one of\r
69	multiple ABIs (Application Binary Interfaces). For example, on some\r
70	32-bit architectures, GnuMP may be configured to represent a limb as\r
71	either a 32-bit <span class="monospaced">long</span> or as a 64-bit <span class="monospaced">long long</span>. Similarly, GnuMP\r
72	may be configured to use specific CPU features.\r
73	</p>\r
74	<div class="paragraph"><p>In order to efficiently use the GnuMP library, MLton represents an\r
75	<span class="monospaced">IntInf.int</span> value in a manner compatible with the GnuMP library’s\r
76	representation of a limb. Hence, it is important that MLton and the\r
77	GnuMP library agree upon the representation of a limb.</p></div>\r
78	<div class="ulist"><ul>\r
79	<li>\r
80	<p>\r
81	When using a source package of MLton, building will detect the\r
82	GnuMP library’s representation of a limb.\r
83	</p>\r
84	</li>\r
85	<li>\r
86	<p>\r
87	When using a binary package of MLton that is dynamically linked\r
88	against the GnuMP library, the build machine and the install machine\r
89	must have the GnuMP library configured with the same representation of\r
90	a limb. (On the other hand, the build machine need not have the GnuMP\r
91	library configured with CPU features compatible with the install\r
92	machine.)\r
93	</p>\r
94	</li>\r
95	<li>\r
96	<p>\r
97	When using a binary package of MLton that is statically linked\r
98	against the GnuMP library, the build machine and the install machine\r
99	need not have the GnuMP library configured with the same\r
100	representation of a limb. (On the other hand, the build machine must\r
101	have the GnuMP library configured with CPU features compatible with\r
102	the install machine.)\r
103	</p>\r
104	<div class="paragraph"><p>However, MLton will be configured with the representation of a limb\r
105	from the GnuMP library of the build machine. Executables produced by\r
106	MLton will be incompatible with the GnuMP library of the install\r
107	machine. To <em>reconfigure</em> MLton with the representation of a limb\r
108	from the GnuMP library of the install machine, one must edit:</p></div>\r
109	<div class="listingblock">\r
110	<div class="content monospaced">\r
111	<pre>/usr/lib/mlton/self/sizes</pre>\r
112	</div></div>\r
113	<div class="paragraph"><p>changing the</p></div>\r
114	<div class="listingblock">\r
115	<div class="content monospaced">\r
116	<pre>mplimb = ??</pre>\r
117	</div></div>\r
118	<div class="paragraph"><p>entry so that <span class="monospaced">??</span> corresponds to the bytes in a limb; and, one must edit:</p></div>\r
119	<div class="listingblock">\r
120	<div class="content monospaced">\r
121	<pre>/usr/lib/mlton/sml/basis/config/c/arch-os/c-types.sml</pre>\r
122	</div></div>\r
123	<div class="paragraph"><p>changing the</p></div>\r
124	<div class="listingblock">\r
125	<div class="content monospaced">\r
126	<pre>(* from "gmp.h" *)\r
127	structure C_MPLimb = struct open Word?? type t = word end\r
128	functor C_MPLimb_ChooseWordN (A: CHOOSE_WORDN_ARG) = ChooseWordN_Word?? (A)</pre>\r
129	</div></div>\r
130	<div class="paragraph"><p>entries so that <span class="monospaced">??</span> corresponds to the bits in a limb.</p></div>\r
131	</li>\r
132	</ul></div>\r
133	</li>\r
134	</ul></div>\r
135	</div>\r
136	</div>\r
137	</div>\r
138	<div id="footnotes"><hr></div>\r
139	<div id="footer">\r
140	<div id="footer-text">\r
141	</div>\r
142	<div id="footer-badges">\r
143	</div>\r
144	</div>\r
145	</body>\r
146	</html>\r