README

   1 (* README
   2  * Author: Frank Pfenning <fp@cs.cmu.edu>
   3  *)
   4
   5 -----------------------------------------------------------------------
   6 Welcome to 15-411 F08!
   7 -----------------------------------------------------------------------
   8
   9 This is some starter code for the L1 compiler you have to build for
  10 the Lab1.  It contains a lexer, parser, translator, and even a code
  11 generator, except that the code generator creates pseudo assembly
  12 language with fictitious instructions and an unlimited number of
  13 registers.  We took some care to use good style (according to the
  14 instructor); you may consider this a model for your own coding.  Feel
  15 free to modify any and all of this code as you see fit.
  16
  17 Bug reports to the instructor Frank Pfenning <fp@cs.cmu.edu> are
  18 particularly welcome and will be noted in the extra credit category.
  19
  20 -----------------------------------------------------------------------
  21 SML Notes
  22 -----------------------------------------------------------------------
  23 There are many different compilers for SML, perhaps the most
  24 popular ones are
  25
  26   SML/NJ  -- http://www.smlnj.org/
  27   MLton   -- http://www.mlton.org/
  28   Poly/ML -- http://www.polyml.org/
  29
  30 In this class we will be using SML/NJ v110.59.  Please make sure your
  31 code compiles under specifically this version on the lab machines
  32 where it is the default and can be invoked simply with "sml" in a
  33 shell.
  34
  35 If you develop your implementation on other machines, similar versions
  36 of SML/NJ are likely to be compatible, but you should certainly check
  37 your code on the lab machines.
  38
  39 For (almost universal) Standard Basis Libraries, see
  40 http://www.standardml.org/Basis/index.html.  Further resources, such
  41 as documentation for ML-Lex and ML-Yacc, and documentation for the SML/NJ
  42 specific libraries which are used in the starter code, can be found at
  43
  44   http://www.cs.cmu.edu/~fp/courses/15411-f08/resources.html
  45
  46 ------------------------------------------------------------------------
  47 Source Files
  48 ------------------------------------------------------------------------
  49 The following are the source files for the L1 compiler
  50
  51 README               -- this file
  52
  53 Makefile             -- makefile for the compiler
  54                         For a quick test
  55
  56     % make l1c          (generates file bin/l1c.heap.<os-tag>)
  57     % bin/l1c --verbose ../tests/test1.c
  58
  59                         should generate ../tests/test1.s in pseudo assembly
  60
  61     % make clean        (removes generated files)
  62     % make TAGS         (creates file TAGS, for Emacs tags commands)
  63
  64 compile-l1c.sml      -- SML commands that will create bin/l1c.heap.<os-tag>
  65 bin/l1c              -- the script that will run the exported SML heap
  66
  67 sources.cm           -- lists all source files, including libraries,
  68                         and lexer and grammar specifications
  69                         For a quick test
  70
  71     % sml
  72     - CM.make "sources.cm";
  73     - Top.test "--verbose ../tests/test1.c";
  74
  75                         should generate ../tests/test1.s in pseudo assembly
  76
  77 parse/ast.sml        -- definition and printer for abstract syntax trees (AST's)
  78 parse/l1.lex         -- L1 lexer
  79 parse/l1.grm         -- L1 grammar
  80 parse/parse.sml      -- L1 parser
  81 parse/parsestate.sml -- L1 parser support for error messages
  82
  83 type/typechecker.sml -- (trivial) type-checker for AST
  84
  85 trans/temp.sml       -- functions to generate and track temp's
  86 trans/tree.sml       -- definition and pretty printer for IR trees
  87 trans/trans.sml      -- translation from AST to IR trees
  88
  89 codegen/assem.sml    -- pseudo assembly format for this starter code
  90 codegen/codegen.sml  -- pseudo code generator
  91
  92 util/errormsg.sml    -- error message utilities
  93 util/flag.sml        -- library for defining flags
  94 util/mark.sml        -- library for tracking source file positions
  95 util/safe-io.sml     -- I/O utilities
  96 util/symbol.sml      -- symbol table library
  97 util/word32.sml      -- machine word utilities for two's complement interpretation
  98
  99 top/top.sml          -- top level function for export to binary and testing
 100
 101 ------------------------------------------------------------------------
 102 Debugging Hints
 103 ------------------------------------------------------------------------
 104 You can use
 105
 106   - Top.test "--verbose --dump-ast --dump-ir --dump-assem file.l1";
 107
 108 to print information from all the phases of the current compiler.
 109
 110 If you want to see the internal representations, you can call directly
 111 on SML's top level:
 112
 113   - val ast = Parse.parse "file.l1";
 114   - val ir = Trans.translate ast;
 115   - val assem = Codegen.codgen ir;
 116
 117 This will use SML's internal printing function to print the data
 118 structures.  However, not everything will show.
 119
 120 "-" means that the type is opaque.  Sometimes you can replace an opaque
 121     signature ascription ":>" with a transparent one ":" to see the info.
 122     For reasons of general hygiene, however, you should change it back
 123     before handing in.
 124
 125 "#" means that the printing depth is exceeded.  Use
 126
 127       - Control.Print.printDepth := 100;
 128
 129     to increase the depth if you need to see more.
 130
 131 "..." means that the printing length is exceeded.  Use
 132
 133       - Control.Print.printLength := 1000;
 134
 135     to increase the length if you need to see more.
 136
 137 ------------------------------------------------------------------------
 138 Library Hints
 139 ------------------------------------------------------------------------
 140 See util/symbol.sml for some uses of libraries provided with SML/NJ
 141 (and some other SML implementations).  BinaryMapFn and
 142 BinarySetFn are likely of general use.  To see their interface,
 143 you can check http://www.smlnj.org/doc/smlnj-lib/Manual/toc.html.
 144 I found binary maps and binary sets to be occasionally helpful.