Some instructions on how to get started hacking the Knit compiler.

  1) Install a Haskell interpreter.
     (For production use, you'll want a compiler but we'll get to that later.)
  2) Learn a few Haskell basics: syntax, types, libraries, etc.
  3) Focus on the important modules in Knit.


1) Install a Haskell interpreter.

   How to install Hugs in $HOME/local
   
     fetch ftp://www.cse.ogi.edu/pub/pacsoft/hugs/hugs98-Feb2000.tar.gz
     tar zxvf hugs98-Feb2000.tar.gz
     
     cd hugs98/src/unix
     ./configure --prefix=$HOME/local --with-readline
     cd ..
     make install  
     # Add $HOME/local/bin to your PATH.
     # Add HUGSFLAGS='-w -E"emacsclient +%d %s"' to your environment (maybe).
     # (If you use Hugs from inside emacs, add +q to HUGSFLAGS as well.)
   
   and to test it:
   
     $HOME/local/bin/hugs $HOME/local/share/hugs/demos/Say
     putStr (say "  /Hugs")
     :quit
   

2) Learn a few Haskell basics: syntax, types, libraries, etc.

   Here's some documentation pointers.  I've tried to indicate the order
   in which to read them and which sections to read/ignore.
   
   The Hugs manual:
   
     http://www.cse.ogi.edu/PacSoft/projects/Hugs/pages/hugsman/index.html
     -- ignore sections 6-10 (extensions, libraries, etc)
   
   The Haskell tutorial:
   
     http://haskell.org/tutorial/
     -- pay particular attention to "do notation" and to how datatypes
     -- are declared.  Ignore field labels (section 6.2) which are not
     -- used inside Knit (or any other large Haskell program).
   
   The Haskell libraries:
   
     http://haskell.org/onlinelibrary/
     -- List and Maybe are the most useful, ignore the rest but consider
     -- coming back to them later
   
     (see also knit/compiler/ListUtils.hs)
   
   The Haskell report:
   
     http://haskell.org/onlinereport/
   
     Mostly for reference but PreludeList is useful to read in its
     entirety.
   
       http://haskell.org/onlinereport/standard-prelude.html#sectA.1

     as are the following common functions:

       id        :: a -> a
       const     :: a -> b -> a
       (.)       :: (b -> c) -> (a -> b) -> (a -> c)
       ($)       :: (a -> b) -> (a -> b)
       fst       :: (a,b) -> a
       snd       :: (a,b) -> b
       error     :: String -> a
       undefined :: a  -- equivalent to 'error "undefined"'

     The apparently pointless function $ is useful because it has different
     precedence and so lets you omit parentheses.  The following are 
     equivalent:

         f $ x        ==  f x
         f $ g x      ==  f (g x)
         f $ g $ h x  ==  f (g (h x))

   The unofficial standard libraries (distributed with most compilers
    but not yet blessed by the committee)
   
     http://www.haskell.org/ghc/docs/latest/hslibs/book1.html
     (especially Pretty (module 7.1))
   
     (see also knit/compiler/PPUnits.hs and knit/compiler/PrettyUtils.hs)
   
   Parser combinators 
   
     Section 5 of Wadler's "Monads for functional programming"
     http://cm.bell-labs.com/cm/cs/who/wadler/topics/monads.html#marktoberdorf
   
     do-notation is used heavily when parsing (instead of using list
     comprehensions).
     The names differ significantly because I tried to emphasise
     similarities between printing and parsing through using similar
     naming conventions and because of the influence of other libraries.
     
     (see also knit/compiler/ParseUnits.hs and knit/compiler/ParserUtils.hs)
   

3) Focus on the important modules in Knit.

   Within the Knit source code, ignore everything to do with C parsing
   - it's only used if you turn flattening on.
   
   Recommended order for understanding knit/compiler/*.hs
   
     AbstractUnits.hs   -- defines abstract syntax for units
     PPUnits.hs         -- defines pretty-printer  for units
     ParseUnits.hs      -- defines parser          for units
     EvalUnits.hs       -- this is where most work is needed
   
   Other parts can be read on-demand as you see a type or function whose
   name you don't recognise.  When following such links, try to read just
   the type of the function and any associated comments.  Only read the
   function definition if the type and comment aren't enough to make a
   reasonable guess.
   
   When editing Haskell code, it is useful to typecheck your program
   at regular intervals.  This can be done by invoking Hugs on EvalUnits.hs
   
     hugs EvalUnits.hs

   and then using :reload (abbreviated to :r) to reload the code when
   you want to recheck your changes.
   
   (You can't load the entire program into Hugs since some parts require
   use of 'GreenCard' (another program) which I haven't told you how to
   install yet.)
   


ToDo: 4) Building and running the complete system
      5) Installing a Haskell compiler

