Return to howto-boot CVS log

Up to [Research Unix] / researchv10no / cmd / sml / doc

Annotation of researchv10no/cmd/sml/doc/howto-boot, revision 1.1.1.1

1.1       root        1:                        How to bootstrap ML
                      2: 
                      3: This is stuff that "src/makeml" does for you, but if you're implementing
                      4: a new runtime system or a new code generator, you need to know what
                      5: makeml is doing.  This is a summary by Norman Ramsey of information
                      6: that Andrew Appel should have written down.
                      7: 
                      8: runtime/run is the ML loader.  It searches for things it needs in the
                      9: mo directory.  It takes one argument, which is the name of a
                     10: structure.  That structure is found in the mo directory and executed
                     11: for side effects.
                     12: 
                     13: runtime/run loads only 4 .mo files:
                     14:        CoreFunc.mo  Math.mo Initial.mo Loader.mo
                     15: It passes its argument (a structure name) to Loader.mo, which then
                     16: loads many other .mo files (the entire DAG of dependencies whose root
                     17: is CompFoo.mo (or whatever)).
                     18: 
                     19: The mo directory contains mo files.  These carry names of top-level
                     20: structures or functors.  They are copies of the output produced by the
                     21: code generator.  As such they are machine-dependent.  There is no
                     22: software support for figuring out to which code generator (or machine)
                     23: a .mo file corresponds.  Thus it is entirely up to the user to make
                     24: sure that the .mo files in the .mo directory make sense and are the
                     25: right ones for the task at hand.
                     26: 
                     27: The highest-level structure of a mo file is: 
                     28:    fn () => (["a","b","c"], fn [a,b,c] => top-level structure or functor)
                     29: where the ["a", "b", "c"] is a list of names of structures on which
                     30: the top-level thing depends, and the [a,b,c] are the structures
                     31: themselves.  Thus a, b, and c are the only free variables in the
                     32: top-level structure, and the thing in the mo file is actually a closed
                     33: lambda-term.  Only the run program reads .mo files.  
                     34: 
                     35: 
                     36: The CompFoo structure (created with the Batch functor) is a structure
                     37: that executes a small batch compiler as a side effect.  IntFoo is a
                     38: structure that executes the full interactive system as a side effect.
                     39: The only difference between the two is in the user interface.  The
                     40: `run' loader is typically used only on one of these two structures, to
                     41: execute either the batch or the interactive system.  Both the batch
                     42: and interactive systems support an `export ML' command that saves the
                     43: currently executing system into a file in a.out format, so that it can
                     44: be re-executed at will.
                     45: 
                     46: 
                     47: The batch system has three interesting commands that deal with ML
                     48: source.  They are:
                     49:    !file   compile file, and write a .mo file for each top-level structure
                     50:    *file   compile file, and write a .s file for each top-level structure
                     51:    <file   read in and parse the file
                     52: All three commands enter appropriate things into the batch compiler's
                     53: symbol table, so that later files can refer to them, and the
                     54: appropriate top-level references can be resolved.
                     55: 
                     56: It is possible to set batch options with
                     57:        ^option
                     58: The options ^printit and ^saveLvarNames will cause useful intermediate
                     59: code to be written to the .s file, in addition to the assembly code.
                     60: 
                     61: 
                     62: 
                     63: 
                     64: Procedure for cross-development
                     65: 
                     66: Here's how to build a Mips ML, given a Vax ML.  To be able to begin, we
                     67: either have to have 
                     68:    a) the .mo files needed for a Vax image of a compiler for a Vax target
                     69: or
                     70:    b) a batch system running on the Vax that generates code for the Vax.
                     71: 
                     72: If we have a) we can get to b) by the following steps:
                     73:    -- type `run CompVax'.  when the dust settles you will be running b).
                     74:    -- type >batch to save the batch system
                     75: 
                     76: The structure CompMipsLittle specifies a batch compiler that will
                     77: generate code for a little-endian Mips.  Suppose this lives in
                     78: mipsglue.sml.  Then we run our `batch' with the command !mipsglue.sml,
                     79: which will create the CompMipsLittle.mo file.  We go park that in the
                     80: .mo directory.  Similarly we may need to compile other parts of the
                     81: Mips code generator and create mo files for them.  The list of Mips
                     82: files is in ./mipsall.
                     83: 
                     84: Now we can use the bootstrap loader (run) to create a new batch,
                     85: batchm, that runs on the Vax but generates code for the mips.  
                     86: `run CompMipsLittle' will do the job, and then we can export the new
                     87: batch by `>batchm'.
                     88: 
                     89: Now we're in a position to throw out all of our old, boring Vax .mo
                     90: files, and to replace them with new, exciting Mips .mo files.  We're
                     91: the only ones who will know the difference---we'll only be able to
                     92: tell the difference when' run fails to work. `mv mo mo.vax' will save
                     93: the vax mo files for a rainy day.
                     94: 
                     95: Then we run batchm on a long script that compiles the whole compiler,
                     96: this time generating Mips code.  This process may take about an hour
                     97: on notecnirp.  The long script is the famous `all'.  We'll then have
                     98: to go park all the newly-created mo files in the newly-created (Mips)
                     99: mo directory.
                    100: 
                    101: Finally we have all our new improved Mips .mo files in place in the mo
                    102: directory.  We're not ready to go yet, though, because we don't yet
                    103: have a Mips loader.  If you've been wondering when we would get a
                    104: runtime system, this is it.  We move to the Mips, go into ./runtime,
                    105: remove all the object code, and adjust the Makefile to indicate we're
                    106: generating a system for the Mips.  We then build a new loader with
                    107: `make run'.  This will compile the runtime system and the loader and
                    108: will squirrel them both away in `run'.  Next we `run CompMipsLittle'
                    109: to get a Mips batch system.  We can also `run IntMipsLittle' to get a
                    110: Mips interactive system.  We can run the interactive system, and we
                    111: can use the batch system to make a new compiler.
                    112: 
                    113: 
                    114: Making a new compiler
                    115: 
                    116: Use the appropriate batch to generate appropriate .mo files.
                    117: Then use the boot loader (run) to generate a new compiler.
                    118: There it is.
                    119: 
                    120: 
                    121: 
                    122: Baby steps
                    123: 
                    124: When debugging the mips code generator, it might be worth replacing
                    125: CoreFunc with a very simple structure ("hello world"), then using
                    126: batchm to generate a fake CoreFunc.mo. runtime/run would execute
                    127: CoreFunc before dying in Math or Initial.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.