Installation
============

MLton runs on a variety of platforms and is distributed in both source and
binary form.

A `.tgz` or `.tbz` binary package can be extracted at any location, yielding
`README.adoc` (this file), `CHANGELOG.adoc`, `LICENSE`, `Makefile`, `bin/`,
`lib/`, and `share/`.  The compiler and tools can be executed in-place (e.g.,
`./bin/mlton`).

A small set of `Makefile` variables can be used to customize the binary package
via `make update`:

 * `CC`: Specify C compiler.  Can be used for alternative tools (e.g.,
   `CC=clang` or `CC=gcc-7`).
 * `WITH_GMP_DIR`, `WITH_GMP_INC_DIR`, `WITH_GMP_LIB_DIR`: Specify GMP include
   and library paths, if not on default search paths.  (If `WITH_GMP_DIR` is
   set, then `WITH_GMP_INC_DIR` defaults to `$(WITH_GMP_DIR)/include` and
   `WITH_GMP_LIB_DIR` defaults to `$(WITH_GMP_DIR)/lib`.)

For example:

[source,sml]
----
$ make CC=clang WITH_GMP_DIR=/opt/gmp update
----

On typical platforms, installing MLton (after optionally performing
`make update`) to `/usr/local` can be accomplished via:

[source,sml]
----
$ make install
----

A small set of `Makefile` variables can be used to customize the installation:

 * `PREFIX`: Specify the installation prefix.
 * `CC`: Specify C compiler.  Can be used for alternative tools (e.g.,
   `CC=clang` or `CC=gcc-7`).
 * `WITH_GMP_DIR`, `WITH_GMP_INC_DIR`, `WITH_GMP_LIB_DIR`: Specify GMP include
   and library paths, if not on default search paths.  (If `WITH_GMP_DIR` is
   set, then `WITH_GMP_INC_DIR` defaults to `$(WITH_GMP_DIR)/include` and
   `WITH_GMP_LIB_DIR` defaults to `$(WITH_GMP_DIR)/lib`.)

For example:

[source,sml]
----
$ make PREFIX=/opt/mlton install
----

Installation of MLton creates the following files and directories.

* ++__prefix__/bin/mllex++
+
The <:MLLex:> lexer generator.

* ++__prefix__/bin/mlnlffigen++
+
The <:MLNLFFI:ML-NLFFI> tool.

* ++__prefix__/bin/mlprof++
+
A <:Profiling:> tool.

* ++__prefix__/bin/mlton++
+
A script to call the compiler.  This script may be moved anywhere,
however, it makes use of files in ++__prefix__/lib/mlton++.

* ++__prefix__/bin/mlyacc++
+
The <:MLYacc:> parser generator.

* ++__prefix__/lib/mlton++
+
Directory containing libraries and include files needed during compilation.

* ++__prefix__/share/man/man1/{mllex,mlnlffigen,mlprof,mlton,mlyacc}.1++
+
Man pages.

* ++__prefix__/share/doc/mlton++
+
Directory containing the user guide for MLton, mllex, and mlyacc, as
well as example SML programs (in the `examples` directory), and license
information.


== Hello, World! ==

Once you have installed MLton, create a file called `hello-world.sml`
with the following contents.

----
print "Hello, world!\n";
----

Now create an executable, `hello-world`, with the following command.
----
mlton hello-world.sml
----

You can now run `hello-world` to verify that it works.  There are more
small examples in ++__prefix__/share/doc/mlton/examples++.


== Installation on Cygwin ==

When installing the Cygwin `tgz`, you should use Cygwin's `bash` and
`tar`.  The use of an archiving tool that is not aware of Cygwin's
mounts will put the files in the wrong place.
