utils/ext-core/README

   1 This package has moved to Hackage!
   2 http://hackage.haskell.org/package/extcore-0.2
   3
   4 The version of the stand-alone External Core library in the GHC
   5 source tree is now out-of-date, and will probably go away eventually.
   6 Please get the latest version from Hackage.
   7
   8 =====================================================================
   9
  10 A set of example programs for handling external core format.
  11
  12 In particular, typechecker and interpreter give a precise semantics.
  13 ---------------------
  14 tjc April/May 2008:
  15
  16 ==== Documentation ====
  17
  18 Documentation for the External Core format lives under docs/ext-core in the
  19 GHC tree. If you are building from HEAD, do not rely on the version of the
  20 External Core documentation that lives in haskell.org -- it is obsolete!
  21
  22 ==== Notes ====
  23
  24 The checker should work on most programs. Bugs (and infelicities)
  25 I'm aware of:
  26
  27 1. There's some weirdness involving funny character literals. This can
  28    be fixed by writing a new lexer for chars rather than using Parsec's
  29    built-in charLiteral lexer. But I haven't done that.
  30
  31 2. The test driver attempts to find module dependencies automatically,
  32    but it's slow. You can turn it off with the "-n" flag to the driver,
  33    and specify all dependencies on the command line (you have to include
  34    standard library dependencies too.)
  35      * It would help to cache dependency info for standard libraries
  36        in a file, or something, but that's future work.
  37
  38 3. To avoid implementing some of the I/O primitives and foreign calls,
  39    I use a gross hack involving replacing certain standard library
  40    modules with simplified versions (found under lib/) that depend on
  41    fake "primops" that the Core interpreter implements. This makes it
  42    difficult (if not impossible) to load optimized versions of standard
  43    libraries right now. Fixing this is future work too.
  44
  45 Typechecking all the GHC libraries eats about a gig of heap and takes a
  46 long time. I blame Parsec. (Someone who was bored, or understood happy
  47 better than I do, could update the old happy parser, which is still in the
  48 repo.)
  49
  50 The interpreter is also memory-hungry, but works for small programs
  51 that only do simple I/O (e.g., putStrLn is okay; not much more than that)
  52 and don't use Doubles or arrays. For example: exp3_8, gen_regexps, queens,
  53 primes, rfib, tak, wheel-sieve1, and wheel-sieve2, if modified so as not
  54 to take input or arguments.
  55
  56 ==== Building ====
  57
  58 To run the checker and interpreter, you need to generate External Core
  59 for all the base, integer and ghc-prim libraries. This can be done by
  60 adding "-fext-core" to the GhcLibHcOpts in your build.mk file, then
  61 running "make" under libraries/.
  62
  63 Then you need to edit Driver.hs and change "baseDir" to point to your GHC
  64 libraries directory.
  65
  66 Once you've done that, the ext-core library can be built in the usual
  67 Cabal manner:
  68 1. runhaskell Setup.lhs configure
  69 2. runhaskell Setup.lhs build
  70 3. runhaskell Setup.lhs install
  71
  72 Then, you can build the example Driver program with:
  73   ghc -package extcore Driver.hs -o Driver
  74
  75 And finally, you can use the included Makefile to run tests:
  76
  77   make nofibtest (to run the parser/checker on all nofib programs...
  78    for example.)
  79   make libtest (to typecheck all the libraries)
  80
  81 Tested with GHC 6.8.2. I make no claims of portability.
  82
  83