@hackage extcore1.0.2

This package contains a set of example programs for handing GHC's External Core format. The typechecker and interpreter give a precise static and dynamic semantics.

==== Documentation ====

Documentation for the External Core format lives at: http://www.haskell.org/ghc/docs/latest/core.pdf

Since this URL has been known to change, you can also search the web for "An External Representation for the GHC Core Language" (a PDF; make sure the date listed on page 1 is in 2009 or later).

==== Building ====

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

The file Language/Core/PrimEnv.hs can be automatically generated from GHC's primop table. This distribution (as of September 2009) contains a snapshot of GHC 6.10.4's primops. See the sources for Setup.lhs in this directory for how to re-generate this file from a more recent version of GHC (you need a GHC build tree if you want to do this.)

==== Parser warning ====

The parsers in this package don't parse negative rational literals as found in Core generated by GHC 6.10.* or 6.12.2. The bug is in GHC rather than the parsers. The bug is currently fixed in the HEAD (as of June 14, 2010) and will be fixed in GHC 6.12.4. In the meantime, you can get a patch for the stable branch (GHC 6.10) at: http://cs.pdx.edu/~tjc/Patches/core-prettyprinter.dpatch

If you want to use GHC 6.12.* instead, then just pull the HEAD.

==== Running the code ====

The easiest way to run the included checker and interpreter is to install and use the Core Linker, which combines multiple External Core source files into a single source file. Since even a very simple GHC- compiled program relies on many different library modules, this makes the code easier, and (as of September 2009) I haven't recently tested the checker and interpreter on Core programs consisting of sets of multiple modules.

The Core Linker lives at: http://hackage.haskell.org/package/linkcore

To use the tools, you need to generate External Core for all the base, integer and ghc-prim libraries. You need a GHC source tree for this. Adding "-fext-core" to the GhcLibHcOpts in your build.mk file, then run "make" under libraries/.

If you want to run the sample interpreter, then before doing the previous step, you need to apply some library patches that circumvent some of GHC's implementations of I/O functions to avoid exposing primops that the ext-core interpreter doesn't know how to do. In this directory, you'll find a patch called simple_io.dpatch. "darcs apply" it under libraries/base. In addition, base-library.dpatch masks out some additional library code and can be "darcs apply" it under libraries/base. It contains implementations of GHC.Float code that are very likely buggy! This code is mainly meant for demonstrating what you can do, not for generating ext-core code that you can execute without substantial additional work. Finally, download the integer-simple library from: http://darcs.haskell.org/libraries/integer-simple and "darcs apply" the patch in this directory called integer-simple-library.dpatch under libraries/integer-simple.

Once you've compiled all the libraries to Core, installed the Core Linker, and generated an example file from it -- say, hello_out.hcr -- you can try running the checker and interpreter.

To do that, build the example Driver program (included in this directory) with: ghc -package extcore Driver.hs -o Driver and then: ./Driver hello_out.hcr

Of course, you can also import Language.Core.ParsecParser, Language.Core.Check, Language.Core.Interp, etc. from your own programs.

Tested most recently with GHC 6.12.2.

==== Acknowledgments ====

Thanks to Neil Brown for contributing the code in Language.Core.DebugPrinter and to Sönke Hahn for contributing patches updating the library for GHC 7.6.

==== Bugs? ====

Probably. Please direct questions or bug reports both to: Tim Chevalier chevalier@alum.wellesley.edu and to glasgow-haskell-users@haskell.org

==== Notes ==== [Warning: the following notes may be out of date, as of September 2009.]

The checker should work on most programs. Bugs (and infelicities) I'm aware of:

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.

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.