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

<!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>SelfCompiling</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>SelfCompiling</h1>\r
</div>\r
<div id="content">\r
<div id="preamble">\r
<div class="sectionbody">\r
<div class="paragraph"><p>If you want to compile MLton, you must first get the <a href="Sources">Sources</a>. You\r
can compile with either MLton or SML/NJ, but we strongly recommend\r
using MLton, since it generates a much faster and more robust\r
executable.</p></div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_compiling_with_mlton">Compiling with MLton</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>To compile with MLton, you need the binary versions of <span class="monospaced">mlton</span>,\r
<span class="monospaced">mllex</span>, and <span class="monospaced">mlyacc</span> that come with the MLton binary package.  To be\r
safe, you should use the same version of MLton that you are building.\r
However, older versions may work, as long as they don&#8217;t go back too\r
far.  To build MLton, run <span class="monospaced">make</span> from within the root directory of the\r
sources.  This will build MLton first with the already installed\r
binary version of MLton and will then rebuild MLton with itself.</p></div>\r
<div class="paragraph"><p>First, the <span class="monospaced">Makefile</span> calls <span class="monospaced">mllex</span> and <span class="monospaced">mlyacc</span> to build the lexer\r
and parser, and then calls <span class="monospaced">mlton</span> to compile itself.  When making\r
MLton using another version the <span class="monospaced">Makefile</span> automatically uses\r
<span class="monospaced">mlton-stubs.mlb</span>, which will put in enough stubs to emulate the\r
<span class="monospaced">structure MLton</span>.  Once MLton is built, the <span class="monospaced">Makefile</span> will rebuild\r
MLton with itself, this time using <span class="monospaced">mlton.mlb</span> and the real\r
<span class="monospaced">structure MLton</span> from the <a href="BasisLibrary">Basis Library</a>.  This second round\r
of compilation is essential in order to achieve a fast and robust\r
MLton.</p></div>\r
<div class="paragraph"><p>Compiling MLton requires at least 1GB of RAM for 32-bit platforms (2GB is\r
preferable) and at least 2GB RAM for 64-bit platforms (4GB is preferable).\r
If your machine has less RAM, self-compilation will\r
likely fail, or at least take a very long time due to paging.  Even if\r
you have enough memory, there simply may not be enough available, due\r
to memory consumed by other processes.  In this case, you may see an\r
<span class="monospaced">Out of memory</span> message, or self-compilation may become extremely\r
slow.  The only fix is to make sure that enough memory is available.</p></div>\r
<div class="sect2">\r
<h3 id="_possible_errors">Possible Errors</h3>\r
<div class="ulist"><ul>\r
<li>\r
<p>\r
The C compiler may not be able to find the <a href="GnuMP">GnuMP</a> header file,\r
<span class="monospaced">gmp.h</span> leading to an error like the following.\r
</p>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>  cenv.h:49:18: fatal error: gmp.h: No such file or directory</pre>\r
</div></div>\r
<div class="paragraph"><p>The solution is to install (or build) GnuMP on your machine.  If you\r
install it at a location not on the default seach path, then run\r
<span class="monospaced">make WITH_GMP_INC_DIR=<em>/path/to/gmp/include</em> WITH_GMP_LIB_DIR=<em>/path/to/gmp/lib</em></span>.</p></div>\r
</li>\r
<li>\r
<p>\r
The following errors indicates that a binary version of MLton could\r
not be found in your path.\r
</p>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>/bin/sh: mlton: command not found</pre>\r
</div></div>\r
<div class="listingblock">\r
<div class="content monospaced">\r
<pre>make[2]: mlton: Command not found</pre>\r
</div></div>\r
<div class="paragraph"><p>You need to have <span class="monospaced">mlton</span> in your path to build MLton from source.</p></div>\r
<div class="paragraph"><p>During the build process, there are various times that the <span class="monospaced">Makefile</span>-s\r
look for a <span class="monospaced">mlton</span> in your path and in <span class="monospaced">src/build/bin</span>.  It is OK if\r
the latter doesn&#8217;t exist when the build starts; it is the target being\r
built.  Failure to find a <span class="monospaced">mlton</span> in your path will abort the build.</p></div>\r
</li>\r
</ul></div>\r
</div>\r
</div>\r
</div>\r
<div class="sect1">\r
<h2 id="_compiling_with_sml_nj">Compiling with SML/NJ</h2>\r
<div class="sectionbody">\r
<div class="paragraph"><p>To compile with SML/NJ, run <span class="monospaced">make bootstrap-smlnj</span> from within the\r
root directory of the sources.  You must use a recent version of\r
SML/NJ.  First, the <span class="monospaced">Makefile</span> calls <span class="monospaced">ml-lex</span> and <span class="monospaced">ml-yacc</span> to build\r
the lexer and parser.  Then, it calls SML/NJ with the appropriate\r
<span class="monospaced">sources.cm</span> file.  Once MLton is built with SML/NJ, the <span class="monospaced">Makefile</span>\r
will rebuild MLton with this SML/NJ built MLton and then will rebuild\r
MLton with the MLton built MLton.  Building with SML/NJ takes\r
significant time (particularly during the "<span class="monospaced">parseAndElaborate</span>" phase\r
when the SML/NJ built MLton is compiling MLton).  Unless you are doing\r
compiler development and need rapid recompilation, we recommend\r
compiling with MLton.</p></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>SelfCompiling</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>SelfCompiling</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>If you want to compile MLton, you must first get the <a href="Sources">Sources</a>. You\r
	32	can compile with either MLton or SML/NJ, but we strongly recommend\r
	33	using MLton, since it generates a much faster and more robust\r
	34	executable.</p></div>\r
	35	</div>\r
	36	</div>\r
	37	<div class="sect1">\r
	38	<h2 id="_compiling_with_mlton">Compiling with MLton</h2>\r
	39	<div class="sectionbody">\r
	40	<div class="paragraph"><p>To compile with MLton, you need the binary versions of <span class="monospaced">mlton</span>,\r
	41	<span class="monospaced">mllex</span>, and <span class="monospaced">mlyacc</span> that come with the MLton binary package. To be\r
	42	safe, you should use the same version of MLton that you are building.\r
	43	However, older versions may work, as long as they don’t go back too\r
	44	far. To build MLton, run <span class="monospaced">make</span> from within the root directory of the\r
	45	sources. This will build MLton first with the already installed\r
	46	binary version of MLton and will then rebuild MLton with itself.</p></div>\r
	47	<div class="paragraph"><p>First, the <span class="monospaced">Makefile</span> calls <span class="monospaced">mllex</span> and <span class="monospaced">mlyacc</span> to build the lexer\r
	48	and parser, and then calls <span class="monospaced">mlton</span> to compile itself. When making\r
	49	MLton using another version the <span class="monospaced">Makefile</span> automatically uses\r
	50	<span class="monospaced">mlton-stubs.mlb</span>, which will put in enough stubs to emulate the\r
	51	<span class="monospaced">structure MLton</span>. Once MLton is built, the <span class="monospaced">Makefile</span> will rebuild\r
	52	MLton with itself, this time using <span class="monospaced">mlton.mlb</span> and the real\r
	53	<span class="monospaced">structure MLton</span> from the <a href="BasisLibrary">Basis Library</a>. This second round\r
	54	of compilation is essential in order to achieve a fast and robust\r
	55	MLton.</p></div>\r
	56	<div class="paragraph"><p>Compiling MLton requires at least 1GB of RAM for 32-bit platforms (2GB is\r
	57	preferable) and at least 2GB RAM for 64-bit platforms (4GB is preferable).\r
	58	If your machine has less RAM, self-compilation will\r
	59	likely fail, or at least take a very long time due to paging. Even if\r
	60	you have enough memory, there simply may not be enough available, due\r
	61	to memory consumed by other processes. In this case, you may see an\r
	62	<span class="monospaced">Out of memory</span> message, or self-compilation may become extremely\r
	63	slow. The only fix is to make sure that enough memory is available.</p></div>\r
	64	<div class="sect2">\r
65	<h3 id="_possible_errors">Possible Errors</h3>\r
66	<div class="ulist"><ul>\r
67	<li>\r
68	<p>\r
69	The C compiler may not be able to find the <a href="GnuMP">GnuMP</a> header file,\r
70	<span class="monospaced">gmp.h</span> leading to an error like the following.\r
71	</p>\r
72	<div class="listingblock">\r
73	<div class="content monospaced">\r
74	<pre> cenv.h:49:18: fatal error: gmp.h: No such file or directory</pre>\r
75	</div></div>\r
76	<div class="paragraph"><p>The solution is to install (or build) GnuMP on your machine. If you\r
77	install it at a location not on the default seach path, then run\r
78	<span class="monospaced">make WITH_GMP_INC_DIR=<em>/path/to/gmp/include</em> WITH_GMP_LIB_DIR=<em>/path/to/gmp/lib</em></span>.</p></div>\r
79	</li>\r
80	<li>\r
81	<p>\r
82	The following errors indicates that a binary version of MLton could\r
83	not be found in your path.\r
84	</p>\r
85	<div class="listingblock">\r
86	<div class="content monospaced">\r
87	<pre>/bin/sh: mlton: command not found</pre>\r
88	</div></div>\r
89	<div class="listingblock">\r
90	<div class="content monospaced">\r
91	<pre>make[2]: mlton: Command not found</pre>\r
92	</div></div>\r
93	<div class="paragraph"><p>You need to have <span class="monospaced">mlton</span> in your path to build MLton from source.</p></div>\r
94	<div class="paragraph"><p>During the build process, there are various times that the <span class="monospaced">Makefile</span>-s\r
95	look for a <span class="monospaced">mlton</span> in your path and in <span class="monospaced">src/build/bin</span>. It is OK if\r
96	the latter doesn’t exist when the build starts; it is the target being\r
97	built. Failure to find a <span class="monospaced">mlton</span> in your path will abort the build.</p></div>\r
98	</li>\r
99	</ul></div>\r
100	</div>\r
101	</div>\r
102	</div>\r
103	<div class="sect1">\r
104	<h2 id="_compiling_with_sml_nj">Compiling with SML/NJ</h2>\r
105	<div class="sectionbody">\r
106	<div class="paragraph"><p>To compile with SML/NJ, run <span class="monospaced">make bootstrap-smlnj</span> from within the\r
107	root directory of the sources. You must use a recent version of\r
108	SML/NJ. First, the <span class="monospaced">Makefile</span> calls <span class="monospaced">ml-lex</span> and <span class="monospaced">ml-yacc</span> to build\r
109	the lexer and parser. Then, it calls SML/NJ with the appropriate\r
110	<span class="monospaced">sources.cm</span> file. Once MLton is built with SML/NJ, the <span class="monospaced">Makefile</span>\r
111	will rebuild MLton with this SML/NJ built MLton and then will rebuild\r
112	MLton with the MLton built MLton. Building with SML/NJ takes\r
113	significant time (particularly during the "<span class="monospaced">parseAndElaborate</span>" phase\r
114	when the SML/NJ built MLton is compiling MLton). Unless you are doing\r
115	compiler development and need rapid recompilation, we recommend\r
116	compiling with MLton.</p></div>\r
117	</div>\r
118	</div>\r
119	</div>\r
120	<div id="footnotes"><hr></div>\r
121	<div id="footer">\r
122	<div id="footer-text">\r
123	</div>\r
124	<div id="footer-badges">\r
125	</div>\r
126	</div>\r
127	</body>\r
128	</html>\r