Change a use of xargs to "$(XARGS)" $(XARGS_OPTS)

[ghc-hetmet.git] / utils / ext-core / README

diff --git a/utils/ext-core/README b/utils/ext-core/README
index 6091935..8191b71 100644 (file)
--- a/utils/ext-core/README
+++ b/utils/ext-core/README
@@ -1,25 +1,46 @@
+This package has moved to Hackage!
+http://hackage.haskell.org/package/extcore-0.2
+
+The version of the stand-alone External Core library in the GHC
+source tree is now out-of-date, and will probably go away eventually.
+Please get the latest version from Hackage.
+
+=====================================================================
+
 A set of example programs for handling external core format.
 
 In particular, typechecker and interpreter give a precise semantics.
 ---------------------
 tjc April/May 2008:
 
+==== Documentation ====
+
+Documentation for the External Core format lives under docs/ext-core in the
+GHC tree. If you are building from HEAD, do not rely on the version of the
+External Core documentation that lives in haskell.org -- it is obsolete!
+
 ==== Notes ====
 
-The checker should work on most programs. Bugs I'm aware of:
-1. There's some business I don't quite understand involving
-   coercions and subkinding (for details, see:
-   http://www.haskell.org/pipermail/cvs-ghc/2008-April/041949.html)
-   This shows up when typechecking a few of the library modules.
+The checker should work on most programs. Bugs (and infelicities) 
+I'm aware of:
    
-2. There's some weirdness involving funny character literals. This can
+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.
 
-3. When typechecking the ghc-prim:GHC.PrimopWrappers library module,
-   some declarations seem to have the wrong type signature (due to 
-   confusion between (forall (t::*) ...) and (forall (t::?) ...).)
-   This is because the ? kind is not expressible in Haskell.
+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
@@ -42,11 +63,20 @@ 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...
+Once you've done that, the ext-core library can be built in the usual
+Cabal manner:
+1. runhaskell Setup.lhs configure
+2. runhaskell Setup.lhs build
+3. runhaskell Setup.lhs install
+
+Then, you can build the example Driver program with:
+  ghc -package extcore Driver.hs -o Driver
+
+And finally, you can use the included Makefile to run tests:
+
+  make nofibtest (to run the parser/checker on all nofib programs...
    for example.)
+  make libtest (to typecheck all the libraries)
 
 Tested with GHC 6.8.2. I make no claims of portability.