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     ! 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.