X-Git-Url: http://git.megacz.com/?p=ghc-hetmet.git;a=blobdiff_plain;f=utils%2Fext-core%2FREADME;h=bb5f3aade52e3cefb175b6ff4b97d6aa5b6492d0;hp=6b8168d25b07b6d4e21acbc6c7a1637c15e9ef8d;hb=8bfeb25ae78e99c7014113468b0057342db4208f;hpb=276585028d51a2516a31b91a91a1f4bba5c9f8ba

diff --git a/utils/ext-core/README b/utils/ext-core/README
index 6b8168d..bb5f3aa 100644
--- a/utils/ext-core/README
+++ b/utils/ext-core/README
@@ -1,11 +1,59 @@
 A set of example programs for handling external core format.
 
 In particular, typechecker and interpreter give a precise semantics.
+---------------------
+tjc April/May 2008:
 
-All can be built using, e.g.,
+==== Notes ====
 
-happy -o Parser.hs Parser.y
-ghc --make -package text -fglasgow-exts  -o Driver Driver.hs
+The checker should work on most programs. Bugs (and infelicities) 
+I'm aware of:
+   
+1. There's some weirdness involving funny character literals. This can
+   be fixed by writing a new lexer for chars rather than using Parsec's
+   built-in charLiteral lexer. But I haven't done that.
+
+2. The test driver attempts to find module dependencies automatically,
+   but it's slow. You can turn it off with the "-n" flag to the driver,
+   and specify all dependencies on the command line (you have to include
+   standard library dependencies too.)
+     * It would help to cache dependency info for standard libraries
+       in a file, or something, but that's future work.
+
+3. To avoid implementing some of the I/O primitives and foreign calls,
+   I use a gross hack involving replacing certain standard library
+   modules with simplified versions (found under lib/) that depend on
+   fake "primops" that the Core interpreter implements. This makes it
+   difficult (if not impossible) to load optimized versions of standard
+   libraries right now. Fixing this is future work too.
+
+Typechecking all the GHC libraries eats about a gig of heap and takes a
+long time. I blame Parsec. (Someone who was bored, or understood happy
+better than I do, could update the old happy parser, which is still in the
+repo.)
+
+The interpreter is also memory-hungry, but works for small programs
+that only do simple I/O (e.g., putStrLn is okay; not much more than that)
+and don't use Doubles or arrays. For example: exp3_8, gen_regexps, queens,
+primes, rfib, tak, wheel-sieve1, and wheel-sieve2, if modified so as not
+to take input or arguments.
+
+==== Building ====
+
+To run the checker and interpreter, you need to generate External Core
+for all the base, integer and ghc-prim libraries. This can be done by
+adding "-fext-core" to the GhcLibHcOpts in your build.mk file, then
+running "make" under libraries/.
+
+Then you need to edit Driver.hs and change "baseDir" to point to your GHC
+libraries directory.
+
+Once you've done that:
+1. make prims (to generate the primops file)
+2. make
+3. make nofibtest (to run the parser/checker on all nofib programs...
+   for example.)
+
+Tested with GHC 6.8.2. I make no claims of portability.
 
-Most recently tested with GHC 6.8.1. I make no claims of portability. --tjc