doc/guide/src/CrossCompiling.adoc

   1 CrossCompiling
   2 ==============
   3
   4 MLton's `-target` flag directs MLton to cross compile an application
   5 for another platform.  By default, MLton is only able to compile for
   6 the machine it is running on.  In order to use MLton as a cross
   7 compiler, you need to do two things.
   8
   9 1. Install the GCC cross-compiler tools on the host so that GCC can
  10 compile to the target.
  11
  12 2. Cross compile the MLton runtime system to build the runtime
  13 libraries for the target.
  14
  15 To make the terminology clear, we refer to the _host_ as the machine
  16 MLton is running on and the _target_ as the machine that MLton is
  17 compiling for.
  18
  19 To build a GCC cross-compiler toolset on the host, you can use the
  20 script `bin/build-cross-gcc`, available in the MLton sources, as a
  21 template.  The value of the `target` variable in that script is
  22 important, since that is what you will pass to MLton's `-target` flag.
  23 Once you have the toolset built, you should be able to test it by
  24 cross compiling a simple hello world program on your host machine.
  25 ----
  26 % gcc -b i386-pc-cygwin -o hello-world hello-world.c
  27 ----
  28
  29 You should now be able to run `hello-world` on the target machine, in
  30 this case, a Cygwin machine.
  31
  32 Next, you must cross compile the MLton runtime system and inform MLton
  33 of the availability of the new target.  The script `bin/add-cross`
  34 from the MLton sources will help you do this.  Please read the
  35 comments at the top of the script.  Here is a sample run adding a
  36 Solaris cross compiler.
  37 ----
  38 % add-cross sparc-sun-solaris sun blade
  39 Making runtime.
  40 Building print-constants executable.
  41 Running print-constants on blade.
  42 ----
  43
  44 Running `add-cross` uses `ssh` to compile the runtime on the target
  45 machine and to create `print-constants`, which prints out all of the
  46 constants that MLton needs in order to implement the
  47 <:BasisLibrary:Basis Library>.  The script runs `print-constants` on
  48 the target machine (`blade` in this case), and saves the output.
  49
  50 Once you have done all this, you should be able to cross compile SML
  51 applications.  For example,
  52 ----
  53 mlton -target i386-pc-cygwin hello-world.sml
  54 ----
  55 will create `hello-world`, which you should be able to run from a
  56 Cygwin shell on your Windows machine.
  57
  58
  59 == Cross-compiling alternatives ==
  60
  61 Building and maintaining cross-compiling `gcc`'s is complex.  You may
  62 find it simpler to use `mlton -keep g` to generate the files on the
  63 host, then copy the files to the target, and then use `gcc` or `mlton`
  64 on the target to compile the files.