| 1 | SelfCompiling |
| 2 | ============= |
| 3 | |
| 4 | If you want to compile MLton, you must first get the <:Sources:>. You |
| 5 | can compile with either MLton or SML/NJ, but we strongly recommend |
| 6 | using MLton, since it generates a much faster and more robust |
| 7 | executable. |
| 8 | |
| 9 | == Compiling with MLton == |
| 10 | |
| 11 | To compile with MLton, you need the binary versions of `mlton`, |
| 12 | `mllex`, and `mlyacc` that come with the MLton binary package. To be |
| 13 | safe, you should use the same version of MLton that you are building. |
| 14 | However, older versions may work, as long as they don't go back too |
| 15 | far. To build MLton, run `make` from within the root directory of the |
| 16 | sources. This will build MLton first with the already installed |
| 17 | binary version of MLton and will then rebuild MLton with itself. |
| 18 | |
| 19 | First, the `Makefile` calls `mllex` and `mlyacc` to build the lexer |
| 20 | and parser, and then calls `mlton` to compile itself. When making |
| 21 | MLton using another version the `Makefile` automatically uses |
| 22 | `mlton-stubs.mlb`, which will put in enough stubs to emulate the |
| 23 | `structure MLton`. Once MLton is built, the `Makefile` will rebuild |
| 24 | MLton with itself, this time using `mlton.mlb` and the real |
| 25 | `structure MLton` from the <:BasisLibrary:Basis Library>. This second round |
| 26 | of compilation is essential in order to achieve a fast and robust |
| 27 | MLton. |
| 28 | |
| 29 | Compiling MLton requires at least 1GB of RAM for 32-bit platforms (2GB is |
| 30 | preferable) and at least 2GB RAM for 64-bit platforms (4GB is preferable). |
| 31 | If your machine has less RAM, self-compilation will |
| 32 | likely fail, or at least take a very long time due to paging. Even if |
| 33 | you have enough memory, there simply may not be enough available, due |
| 34 | to memory consumed by other processes. In this case, you may see an |
| 35 | `Out of memory` message, or self-compilation may become extremely |
| 36 | slow. The only fix is to make sure that enough memory is available. |
| 37 | |
| 38 | === Possible Errors === |
| 39 | |
| 40 | * The C compiler may not be able to find the <:GnuMP:> header file, |
| 41 | `gmp.h` leading to an error like the following. |
| 42 | + |
| 43 | ---- |
| 44 | cenv.h:49:18: fatal error: gmp.h: No such file or directory |
| 45 | ---- |
| 46 | + |
| 47 | The solution is to install (or build) GnuMP on your machine. If you |
| 48 | install it at a location not on the default seach path, then run |
| 49 | ++make WITH_GMP_INC_DIR=__/path/to/gmp/include__ WITH_GMP_LIB_DIR=__/path/to/gmp/lib__++. |
| 50 | |
| 51 | * The following errors indicates that a binary version of MLton could |
| 52 | not be found in your path. |
| 53 | + |
| 54 | ---- |
| 55 | /bin/sh: mlton: command not found |
| 56 | ---- |
| 57 | + |
| 58 | ---- |
| 59 | make[2]: mlton: Command not found |
| 60 | ---- |
| 61 | + |
| 62 | You need to have `mlton` in your path to build MLton from source. |
| 63 | + |
| 64 | During the build process, there are various times that the `Makefile`-s |
| 65 | look for a `mlton` in your path and in `src/build/bin`. It is OK if |
| 66 | the latter doesn't exist when the build starts; it is the target being |
| 67 | built. Failure to find a `mlton` in your path will abort the build. |
| 68 | |
| 69 | |
| 70 | == Compiling with SML/NJ == |
| 71 | |
| 72 | To compile with SML/NJ, run `make bootstrap-smlnj` from within the |
| 73 | root directory of the sources. You must use a recent version of |
| 74 | SML/NJ. First, the `Makefile` calls `ml-lex` and `ml-yacc` to build |
| 75 | the lexer and parser. Then, it calls SML/NJ with the appropriate |
| 76 | `sources.cm` file. Once MLton is built with SML/NJ, the `Makefile` |
| 77 | will rebuild MLton with this SML/NJ built MLton and then will rebuild |
| 78 | MLton with the MLton built MLton. Building with SML/NJ takes |
| 79 | significant time (particularly during the "`parseAndElaborate`" phase |
| 80 | when the SML/NJ built MLton is compiling MLton). Unless you are doing |
| 81 | compiler development and need rapid recompilation, we recommend |
| 82 | compiling with MLton. |