<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="AsciiDoc 8.6.8">
<title>SelfCompiling</title>
<link rel="stylesheet" href="./asciidoc.css" type="text/css">
<link rel="stylesheet" href="./pygments.css" type="text/css">


<script type="text/javascript" src="./asciidoc.js"></script>
<script type="text/javascript">
/*<![CDATA[*/
asciidoc.install();
/*]]>*/
</script>
<link rel="stylesheet" href="./mlton.css" type="text/css"/>
</head>
<body class="article">
<div id="banner">
<div id="banner-home">
<a href="./Home">MLton 20130715</a>
</div>
</div>
<div id="header">
<h1>SelfCompiling</h1>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>If you want to compile MLton, you must first get the <a href="Sources">Sources</a>. You
can compile with either MLton or SML/NJ, but we strongly recommend
using MLton, since it generates a much faster and more robust
executable.</p></div>
</div>
</div>
<div class="sect1">
<h2 id="_compiling_with_mlton">Compiling with MLton</h2>
<div class="sectionbody">
<div class="paragraph"><p>To compile with MLton, you need the binary versions of <span class="monospaced">mlton</span>,
<span class="monospaced">mllex</span>, and <span class="monospaced">mlyacc</span> that come with the MLton binary package.  To be
safe, you should use the same version of MLton that you are building.
However, older versions may work, as long as they don&#8217;t go back too
far.  To build MLton, run <span class="monospaced">make</span> from within the root directory of the
sources.  This will build MLton first with the already installed
binary version of MLton and will then rebuild MLton with itself.</p></div>
<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
and parser, and then calls <span class="monospaced">mlton</span> to compile itself.  When making
MLton using another version the <span class="monospaced">Makefile</span> automatically uses
<span class="monospaced">mlton-stubs.cm</span>, which will put in enough stubs to emulate the
<span class="monospaced">MLton</span> structure.  Once MLton is built, the <span class="monospaced">Makefile</span> will rebuild
MLton with itself, this time using <span class="monospaced">mlton.cm</span> and the real <span class="monospaced">MLton</span>
structure from the <a href="BasisLibrary">Basis Library</a>.  This second round
of compilation is essential in order to achieve a fast and robust
MLton.</p></div>
<div class="paragraph"><p>Compiling MLton requires at least 512M of actual RAM, and 1G is
preferable.  If your machine has less than 512M, self-compilation will
likely fail, or at least take a very long time due to paging.  Even if
you have enough memory, there simply may not be enough available, due
to memory consumed by other processes.  In this case, you may see an
<span class="monospaced">Out of memory</span> message, or self-compilation may become extremely
slow.  The only fix is to make sure that enough memory is available.</p></div>
<div class="sect2">
<h3 id="_possible_errors">Possible Errors</h3>
<div class="ulist"><ul>
<li>
<p>
If you have errors running <span class="monospaced">latex</span>, you can skip building the
documentation by using <span class="monospaced">make all-no-docs</span>.
</p>
</li>
<li>
<p>
The C compiler may not be able to find the <a href="GnuMP">GnuMP</a> header file,
<span class="monospaced">gmp.h</span> leading to an error like the following.
</p>
<div class="listingblock">
<div class="content monospaced">
<pre> platform/darwin.h:26:36: /usr/local/include/gmp.h: No such file or directory</pre>
</div></div>
<div class="paragraph"><p>The solution is to install (or build) the GnuMP on your machine.  If
you install it at a different location, put the new path in
<span class="monospaced">runtime/platform/<em>&lt;os&gt;</em>.h</span>.</p></div>
</li>
<li>
<p>
The following error indicates that a binary version of MLton could
not be found in your path.
</p>
<div class="listingblock">
<div class="content monospaced">
<pre>.../upgrade-basis: mlton: command not found
Error: cannot upgrade basis because the compiler doesn't work
make[3]: *** [upgrade-basis.sml] Error 1</pre>
</div></div>
<div class="paragraph"><p>You need to have <span class="monospaced">mlton</span> in your path to build MLton from source.</p></div>
<div class="paragraph"><p>During the build process, there are various times that the <span class="monospaced">Makefile`s
look for a `mlton</span> in your path and in <span class="monospaced">src/build/bin</span>.  It is OK if
the latter doesn&#8217;t exist when the build starts; it is the target being
built.  While not finding <span class="monospaced">build/bin/mlton</span> also results in
<span class="monospaced">mlton: command not found</span> error messages, such errors are benign and
will not abort the build.  Failure to find a <span class="monospaced">mlton</span> in your path will
abort the build.</p></div>
</li>
<li>
<p>
Mac OS X executables do not seem to like static libraries to have a
different path location at runtime compared to when the executable was
built.  For example, the binary package for Mac OS X unpacks to
<span class="monospaced">/usr</span>.  If you try to install it in <span class="monospaced">/usr/local</span> you may get the
following errors:
</p>
<div class="listingblock">
<div class="content monospaced">
<pre>/usr/bin/ld: table of contents for archive:
/usr/local/lib/mlton/self/libmlton.a is out of date;
rerun ranlib(1) (can't load from it)</pre>
</div></div>
<div class="paragraph"><p>Although running <span class="monospaced">ranlib</span> seems like the right thing to do, it doesn&#8217;t
actually resolve the problem.  Best bet is to install in <span class="monospaced">/usr</span> and
then either live with this location, or build MLton yourself and
install in <span class="monospaced">/usr/local</span>.</p></div>
</li>
</ul></div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_compiling_with_sml_nj">Compiling with SML/NJ</h2>
<div class="sectionbody">
<div class="paragraph"><p>To compile with SML/NJ, run <span class="monospaced">make nj-mlton</span> from within the root
directory of the sources.  You must use a recent version of SML/NJ.
First, the <span class="monospaced">Makefile</span> calls <span class="monospaced">mllex</span> and <span class="monospaced">mlyacc</span> to build the lexer
and parser.  Then, it calls SML/NJ with the appropriate <span class="monospaced">sources.cm</span>
file.  Building with SML/NJ takes some time (roughly 10 minutes on a
1.6GHz machine).  Unless you are doing compiler development and need
rapid recompilation, we recommend compiling with MLton.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr></div>
<div id="footer">
<div id="footer-text">
</div>
<div id="footer-badges">
</div>
</div>
</body>
</html>
