============================================================================
The Overall Structure of the Current FLINT/ML Compiler 
    <based On SML/NJ version 109.33 11/29/97>



============================================================================
The Overall Structure of the Current FLINT/ML Compiler 
    <based On SML/NJ version 109.31+ 9/22/97>

NOTES
   Some informal half-baked notes. Just don't want to discard them.

README 
   This file which gives an overview of the compiler structure.

all-files.cm
   The standard Makefile for compiling the compiler. It is similar
   to the idea of sources.cm used by CM.make, except that 
   all-files.cm is designed for CMB.make only. The resulting binfiles
   from doing CMB.make are placed in a single bin directory, eg. 
   bin.x86-unix or bin.sparc-unix. Right now, all-files.cm is
   just whatever in sources.cm plus all the bootstrap glue files.

buildcm
   Scripts for building the sml-cm version of the compiler.

buildcm2
   Scripts for building a sml-cm compiler that knows to where to
   find the library and ml-lex and ml-yacc, etc. Need to adjust
   the top-level directory name there.

sources.cm
   This file contains the usual makefile for CM.make. It is not
   used to build up the interactive compiler. But it can be
   useful for debugging purpose as doing CM.make immediately
   build up a interactive visible compiler. Notice all the 
   bootstrap glue files are not here, because CM.make() does 
   run them which will cause problems.

xmakeml 
   Scripts for building the interactive compiler. The default path
   of bin files is ./bin.$arch-$os. If you add the "-full" option,
   it will build a compiler whose components are visible to the
   top-level interactive environment.

xrun 
   Scripts for running the interactive copmiler.

============================================================================
Tips:
   To find a particular binding XXX, type 
        grep XXX */*.{sig,sml,lex,grm} */*/*.{sig,sml,lex,grm}
   If you like, make the above into a script.

0-Boot
   The SML97 Basis Library. When recompiling the compiler (via CMB.make),
   files in this directory are always compiled first. Files in this directory
   are compiled in the following order:
       (0)  build the primitive environment (from 3-Semant/prim/prim.sml)
       (1)  assembly.sig
       (2)  dummy.sml
       (3)  core.sml
       (4)  files in all-files.cm (following the exact order)
       (5)  files in pervasive.cm (following the exact order)
     
1-TopLevel/batch/
   Utility files for the Compilation Manager CM and CMB; 
1-TopLevel/bootstrap/
   How to bootstrap an interactive compiler. Details are in boot.sml and
   shareglue.sml. Before building an interactive compiler, one should have
   already gotten a visible compiler (for that particular architecture),
   see the viscomp directory. To build a compiler for SPARC architecture,
   all we need to do is the load and run the IntSparc (in sparcglue.sml) 
   structure.
1-TopLevel/environ/
   A top-level environment include static environment, dynamic environment
   and symbolic environment. The definitions of static environments are in
   the 3-Semant/statenv directory, as they are mostly used by the elaboration
   and type checking.
1-TopLevel/interact/
   How the top-level interactive loop is organized. The evalloop.sml contains
   the details on how a ML program is compiled from source code to binary
   code and then later being executed.
1-TopLevel/misc/
   Compiler control flags and version numbers are here. 
1-TopLevel/viscomp/
   How to build the visible compiler viscomp --- this is essentially 
   deciding what to export to the outside world. 

2-FrontEnd
   Phase 1 of the compilation process. Turning the SML source code into
   the Concrete Synatx. The definition of concrete syntax is in ast.sml.
   The frontend.sig and frontend.sml files contains the big picture on
   how the lexer and parser are organized.

3-Semant
   So-called semantic analysis, but really doing the elaboration and 
   type-checking of the core and module languages. The semantic objects
   are defined in bindings.sml. The result is the Abstract Syntax, defined
   in the absyn directory
3-Semant/absyn/
   Definition of Abstract Syntax
3-Semant/basics/
   Definition of semantic objects for the core language including type 
   bindings, value bindings, and constructor bindings.
3-Semant/bindings.sml
   Top-level view of what semantic objects we have
3-Semant/elaborate/
   How to turn a piece of code in the Concrete Syntax into one in the
   Abstract Syntax. The top-level organization is in the following 
   elabtop.sml file.
3-Semant/elabtop.sml
   Top-level view of the elaboration process. Notice that each piece
   of core-ML program is first translated into the Abstract Syntax, 
   and gets type-checked. The type-checking does change the contents
   of abstract syntax, as certain type information won't be known
   until type-checking is done.
3-Semant/modules/
   Utility functions for elaborations of modules. The module.sig and
   module.sml contains the definitions of module-level semantic objects.
3-Semant/pickle/
   How to write the static environments into a file! This is important
   if you want to create the *.bin file. It is also useful to infer 
   a unique persistant id for each compilation unit (useful to detect
   the cut-off compilation dependencies).
3-Semant/prim/
   Here is the list of primitive operators and primitive types. All
   are synthesized, and then later get put in the primEnv environment.
   PrimEnv was used as the initial environment when elaborating files
   in the 0-Boot directory.
3-Semant/statenv/
   The definition of Static Environment. The SC-ed version of Static
   Environment is used to avoid environment blow-up.
3-Semant/typing/
   The type-checking and type-inference code for the core-ML programs.
   It is performed on Abstract Syntax and it produces Abstract Syntax
   also.

4-Translate
   This phase translates the Abstract Syntax into the intermediate 
   Lambda language (i.e., FLINT). During the translation, it compiles
   the Pattern Matches (see the mcomp directory). 
4-Translate/lambda/
   Definition of the intermediate languages. How to type-check it
   and how to print it.
4-Translate/mcomp/
   Code for compiling pattern matches.
4-Translate/opt/
   Code for optimization and representation analysis of the Lambda code.
4-Translate/plambda/
   An older version of the Lambda language (not in the A-Normal form)
4-Translate/trans/
   Translation of Abstract Syntax into the Lambda code. Of course, the
   semantic objects used in the elaboration have to be translated into
   the Lambda types as well.
4-Translate/type/
   Definiton of the Lambda types, constructors and kinds. A bunch of
   utility functions on how to manipulate the type environment, deBruijn
   indices, etc.

5-CPS
   This phase turns the Lambda code into Continuation Passing Style,
   does the closure conversion, and then feed it into the code generator.
5-CPS/clos/
   The closure conversion step. Check out Shao/Appel LFP94 paper for
   the detailed algorithm
5-CPS/conv/
   Converting the Lambda code into the CPS code. The main nontrivial
   step is the compilation of the Switch statement.
5-CPS/obsol/
   All files in this directory are currently not up-to-date. They are
   either obsolete or are not compatible with recent changes made to
   the CPS language.
5-CPS/opt/
   The CPS-based optimizations. Check out the Appel Compiling with 
   Continuation book for the details
5-CPS/spillgen/
   This is the OLD code generator, currently used by the SPARC, MIPS,
   RS6000 and X86 architectures. A counterpart of this is the new 
   code generator in the 7-NewCGen/cpscompile directory.
5-CPS/top/
   The toplevel organization of all the above phases.

6-CodeGen
   The old code generator. May eventually go away after Lal's new
   code generator become stable. Each code generator should produce
   a structure of signature CODEGENERATOR (defined in the 
   1-Toplevel/misc/codes.sig file)
6-CodeGen/bytecode/
   These code might be obsolete. It is supposed to generate some
   kind of byte code.
6-CodeGen/coder/
   This directory contains the machine-independent parts of the
   old code generator. Some important signatures are also here.
6-CodeGen/mips/
   MIPS code generator for both little endian and big endian
6-CodeGen/rs6000/
   RS6000 code generator
6-CodeGen/sparc/
   SPARC code generator
6-CodeGen/x86/
   X86 code generator

7-NewCGen/MLRISC/
   Lal George's new code generator ML RISC
7-NewCGen/alpha32/
   Alpha32 new code generator
7-NewCGen/alpha32x/
   Alpha32 new code generator (with special patches)
7-NewCGen/cpscompile/
   Compilation of CPS into the MLRISC abstract machine code
7-NewCGen/hppa/
   HPPA new code genrator

9-Misc/
   Contains various kinds of utility programs
9-Misc/bignums/
   Bignum packages. I have no clue how stable this is.
9-Misc/print/
   Pretty printing. Very Adhoc, needs major clean up.
9-Misc/profile/
   The time and the space profiler.
9-Misc/util/
   Important utility functions including the Inputsource (for 
   reading in a program), and various Hashtable and Dictionary
   implementations.
============================================================================