Return to BATCHINSTALL CVS log

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

Annotation of researchv10no/cmd/sml/doc/BATCHINSTALL, revision 1.1

1.1     ! root        1: Standard ML of New Jersey's Batch Compiler
        !             2: 
        !             3: Description:
        !             4: 
        !             5: The Standard ML of New Jersey batch compiler provides some (unsafe)
        !             6: separate compilation and cross compilation capabilities.  The batch system
        !             7: compiles files containing signature, structure, and functor declarations,
        !             8: i.e. only module level declarations are allowed.  Compiling a module "Foo"
        !             9: produces a corresponding object file "Foo.mo", which contains the names of
        !            10: the other .mo files required to build the module, as well as the code of
        !            11: the module itself.  Modules are compiled separately, producing the
        !            12: necessary .mo files.
        !            13: 
        !            14: A program is executed by passing a module name to the run-time system
        !            15: with the command (assuming src is current working directory):
        !            16: 
        !            17:      runtime/run [memory managment options] Module
        !            18: 
        !            19: The run-time system starts a linker which loads in the module, finds
        !            20: out what other modules it depends on, recursively loads them and
        !            21: passes them to the original module.  The module then "builds" itself,
        !            22: by executing its top-level declarations and creating a run-time
        !            23: structure.  By convention, the loader looks for the module object
        !            24: files in the directory src/mo.  In this case it would look for an
        !            25: object file named src/mo/Module.mo.
        !            26: 
        !            27: For example, batch compiling the following module will create
        !            28: a file named HelloWorld.mo.
        !            29: 
        !            30:        structure HelloWorld =
        !            31:          struct
        !            32:            val foo = print "hello world"
        !            33:          end
        !            34: 
        !            35: When HelloWorld.mo is placed in the directory src/mo and the command
        !            36: 
        !            37:      runtime/run HelloWorld
        !            38: 
        !            39: is executed, the runtime system will build a run-time record
        !            40: containing foo, and as a side effect of building the record, "hello
        !            41: world" will be printed.
        !            42: 
        !            43: Thus a program consists of the collection of all modules on which a
        !            44: given top-level structure (transitively) depends.  The order in which
        !            45: the modules will be executed/created is determined by a postorder
        !            46: traversal of the (acyclic) dependence graph.
        !            47: 
        !            48: Using the batch system for separate compilation is unsafe since the
        !            49: .mo files contain no type information, only the names of the modules
        !            50: on which they directly depend.  However, as long as each module has
        !            51: the correct signature, the run-time record will be type-correct; in
        !            52: other words, it is safe to edit, re-compile, and re-link modules as long
        !            53: their signatures do not change.
        !            54: 
        !            55: 
        !            56: Installation:
        !            57: 
        !            58: The compiler is composed of two parts: a run-time system written in C and
        !            59: assembly language; and a number of ML object files which form the main part
        !            60: of the compiler.  The run-time system provides garbage collection, signal
        !            61: handling, and system calls; the rest of the compiler, including the
        !            62: standard library, is written in ML.  The .mo files for the compiler
        !            63: reside in the mo.vax and mo.m68 subdirectories of the ML distribution.
        !            64: The source for the compiler resides in the src subdirectory, and these
        !            65: instructions assume that the current directory is src.
        !            66: 
        !            67: To build a batch compiler:
        !            68: 
        !            69: 1. Go to the src subdirectory of mldist:
        !            70: 
        !            71:      cd src
        !            72: 
        !            73: 2. Run the makeml script with the -batch option, e.g.
        !            74: 
        !            75:      makeml -batch ...
        !            76: 
        !            77:    The other options for makeml have the same meaning as for the
        !            78:    interactive system.  See the man page doc/makeml.1.
        !            79: 
        !            80:    As the command executes, you should see messages like "[Loading Foo]" and
        !            81:    "[Executing Bar]", which indicate the modules being linked in, and then
        !            82:    messages like "signature ASSEMBLY" and "functor CoreFunc", which
        !            83:    indicate that the standard library is being compiled.
        !            84:    
        !            85:    When the command successfully terminates, an executable image named
        !            86:    "batch" has been created in the current directory.  This is the batch
        !            87:    ML compiler.  If you wish to use a different name for this file, use
        !            88:    the -i option of makeml.
        !            89: 
        !            90:    Now you can run the batch compiler by typing "batch".  You can give it
        !            91:    commands interactively, or by redirecting its input from a file, as is
        !            92:    done below with the command script "all".
        !            93: 
        !            94: 
        !            95: Normally you will want to build a complete interactive or batch
        !            96: system, but there are occasions when you may want to build just the
        !            97: runtime system.  The option -run of makeml will do this.
        !            98: 
        !            99: When invoked, runtime/run takes the name of a module (say "Foo") as a
        !           100: parameter.  It looks for a file with path name mo/Foo.mo relative to
        !           101: the current directory and loads that file, and then recursively loads
        !           102: mo/Bar.mo for all modules Bar on which Foo depends.  Finally the code
        !           103: for creating the module Foo is executed.  For instance, to run the
        !           104: interactive system on a Vax, one could symbolically link mo to
        !           105: mldist/mo.vax (or ../mo.vax if current directory is src) and execute 
        !           106: the command
        !           107: 
        !           108:    runtime/run IntVax
        !           109: 
        !           110: This causes mo/IntVax.mo to be loaded, together with all the modules
        !           111: on which it depends (essentially the whole compiler).  IntVax.mo
        !           112: (defined in src/build/glue.sml) causes the interactive top-level loop
        !           113: to be executed when the functor Interactive is applied.  Any program can
        !           114: be directly loaded and executed by the runtime system in this manner,
        !           115: not just the compiler.
        !           116: 
        !           117: The runtime system accepts the option flags -h, -r, -m, and -g to
        !           118: control heap sizing and garbage collection messages.  These are
        !           119: described in doc/INSTALL.
        !           120: 
        !           121: 
        !           122: Using the batch compiler:
        !           123: 
        !           124: The batch compiler accepts commands on its standard input.  The list of
        !           125: commands is:
        !           126: 
        !           127:      !file      => compile the file.
        !           128:      *file      => assemble the file.
        !           129:      <file      => parse the file.
        !           130:      >file      => export to a file.
        !           131:      %          => print the last generated lambda (intermediate code).
        !           132:      #word      => comment; ignored.
        !           133:      @directory => look for files in a directory.  directory should end in /.
        !           134:      ~function  => execute a function.
        !           135:      ^flag      => toggle a flag.
        !           136:      ?          => print this help message.
        !           137: 
        !           138: There should be no space between the command character and the
        !           139: argument string, which should not be quoted.
        !           140: 
        !           141: The execute ("~") and toggle ("^") commands are mainly used to control
        !           142: debugging facilities, which are not explained here.  Typing "^" alone
        !           143: on a line produces a list of possible flags.
        !           144: 
        !           145: The compile command, "!", causes the named file to be compiled,
        !           146: generating an object file A.mo for each module A defined in the file.
        !           147: The assemble command, "*", generates an assembly listing A.s that can
        !           148: be assembled to produce the corresponding .mo file.  The parse
        !           149: command, "<", causes the file to be parsed and type-checked, but
        !           150: produces no output files.  These three commands all update the symbol
        !           151: table with the bindings defined in the file.  The file must contain
        !           152: only signature, structure, and functor declarations.
        !           153: 
        !           154: The export command ">" exports the current state of the batch compiler
        !           155: to an executable file with the given name.  This is a way of
        !           156: preserving the symbol table state of the compiler, and is useful for
        !           157: separate compilation; if you change a module without changing its
        !           158: signature, you can safely recompile it using the exported compiler
        !           159: (which contains the symbol table information from other modules that
        !           160: the modified module may require).  For example, the file "all" in the
        !           161: src directory is a batch command script for compiling the compiler.
        !           162: The last command in the file exports to a file "upto.all", which can
        !           163: recompile any module of the compiler.
        !           164: 
        !           165: Once you have compiled all of your code, you only need to move it to the
        !           166: mo directory and execute it in the same way as CompM68 or CompVax:
        !           167: 
        !           168:   runtime/run Foo
        !           169: 
        !           170: for a module Foo.  Note that the files CoreFunc.mo, Math.mo (for Vax),
        !           171: Initial.mo, and Loader.mo must be in the mo directory, as they are
        !           172: used in bootstrapping the system.
        !           173: 
        !           174: 
        !           175: Recompiling the compiler
        !           176: 
        !           177: NOTE: Recompiling the compiler will require a heap size of at least
        !           178: 6MB, so it if possible it should be done on a machine with at least
        !           179: 8MB of physical memory.  Use the -m flag of runtime/run to set softmax
        !           180: as high as reasonable (e.g. -m 6000 on an 8MB Sun 3).
        !           181: 
        !           182: NOTE: Beware of using the sharable runtime system when recompiling the
        !           183: compiler, since it has the effect of embedding old versions of the .mo
        !           184: files into the system.  Either use a nonsharable version of
        !           185: runtime/run, or rebuild a sharable runtime/run after each iteration
        !           186: of compiling the compiler to incorporate the latest .mo files.
        !           187: 
        !           188: If you change the compiler, you can use the batch command script "all"
        !           189: to recompile it with the batch system:
        !           190: 
        !           191:        batch < all
        !           192: 
        !           193: or     runtime/run {CompM68 | CompVax | CompSparc | CompNS32} < all    
        !           194: 
        !           195: This will generate new .mo files for all the modules in the compiler including
        !           196: the "boot" modules (whose source files are found in src/boot):
        !           197: 
        !           198:   CoreFunc.mo  [boot/core.sml]
        !           199:   Math.mo (used by Vax only) [boot/math.sml]
        !           200:   Initial.mo  [boot/perv.sml]
        !           201:   Loader.mo   [boot/loader.sml]
        !           202: 
        !           203: These are generated by the "~mBoot" command in the all script rather
        !           204: than using the "!" compile command.  These files are treated
        !           205: differently because of their role in bootstraping the pervasive (i.e.
        !           206: built-in) environment.
        !           207: 
        !           208: The newly generated .mo files should be moved into a new mo directory,
        !           209: say mldist/mo.new:
        !           210: 
        !           211:        cd ..   (to mldist)
        !           212:        mkdir mo.new
        !           213:        mv src/*.mo mo.new
        !           214: 
        !           215: After generating new .mo files for the compiler (including the boot
        !           216: modules if necessary), you should build a new batch compiler by
        !           217: symbolically linking mldist/mo.new to mldist/src/mo and recompiling
        !           218: the source code again (using the -mo option to makeml to designate the
        !           219: object directory).
        !           220: 
        !           221:        cd src
        !           222:        makeml -batch -mo ../mo.new -vax -bsd ...
        !           223:        batch < all
        !           224: 
        !           225: The resulting .mo files should be identical to the previous set of .mo
        !           226: files in mo.new.  Sometimes more than one iteration is necessary (for
        !           227: example if the signature of one of the boot modules has changed).  The
        !           228: bootstrapping is successful when two successive iterations produce
        !           229: identical .mo files.
        !           230: 
        !           231: The last command in the all file causes an image of the batch compiler
        !           232: to be saved in the file upto.all.  This image contains the symbol
        !           233: table information for all the modules in the compiler.  It can be used
        !           234: to recompile individual files in the compiler after they have been
        !           235: modified (but beware of changes in signatures).
        !           236: 
        !           237: 
        !           238: Cross compiling
        !           239: 
        !           240: If you have, say, the Vax object files in mldist/mo.vax and need to build
        !           241: the sparc object files, then you can build a batch compiler to generate
        !           242: sparc object files by using the -target option of makeml:
        !           243: 
        !           244:        makeml -vax -bsd -target sparc
        !           245: 
        !           246: (the -target option implies the -batch option).
        !           247: 
        !           248: Then the resulting batch compiler can be used to generate the sparc mo
        !           249: files by executing (in directory src):
        !           250: 
        !           251:        batch < all
        !           252: 
        !           253: Then make a directory mldist/mo.sparc and move the new object files into
        !           254: this directory.  These object files can then be used to bootstrap the
        !           255: compiler on a sparc machine in the usual way.

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