Transforms a single Haskell module to a single, closed External Core module.
===== Prerequisites ====
For the Core Linker to be useful, you will at least need to have built External
Core for all the GHC libraries.
You also need to install the extcore package from:
http://hackage.haskell.org/package/extcore-0.2
In the README file in the extcore package, there are instructions on building
External Core for the GHC libraries.
The extcore package includes a patch for the GHC libraries (see the README file
in the extcore package.)
There are two ways to proceed:
(1) Build two versions of GHC that are identical except that one version is a stage1
build with some patched libraries, and the other version is exactly the same, but is
a stage2 build without the library patch (as explained previously) applied.
(2) Use a plain old installed version of GHC.
Option (1) will allow you to run the stand-alone External Core interpreter on some
very simple examples, and will illustrate how you can add an appropriate set of
primops so that you can implement your own External Core back-end.
(You need two versions of GHC because the patched libraries can't bootstrap
GHC, but to compile the Core Linker, you need the GHC API, requiring a stage 2 build.)
Option (2) will probably not allow you to execute any Core code, but will still
allow running the Core linker so you can see what it does.
The instructions that follow assume you've done (1).
===== Building =====
Suppose your GHC build tree that contains External Core for the GHC libraries lives under:
$TOP/ghc
and your stage 2 build of GHC, which is identical except that it hasn't had the library
patch applied, lives in:
$TOP/ghc-stage-2
Then you do:
runhaskell -f $TOP/ghc-stage-2/ghc/stage2-inplace/ghc Setup configure --user --with-ghc=$TOP/ghc-stage-2/ghc/stage2-inplace/ghc --with-ghc-pkg=$TOP/ghc-stage-2/utils/ghc-pkg/install-inplace/bin/ghc-pkg --configure-option=--topdir=$TOP/ghc-stage-2/inplace-datadir/ --configure-option=--pkgconf=$TOP/ghc/inplace-datadir/package.conf
What do these options do?
* --topdir points to the GHC library. Notice that you use the stage2 build here.
* --pkgconf points to the package.conf file that points to packages that you've
built External Core for. Not that you use the stage1 build here.
After that, you do:
runhaskell -f $TOP/ghc-stage-2/ghc/stage2-inplace/ghc Setup build
runhaskell -f $TOP/ghc-stage-2/ghc/stage2-inplace/ghc Setup install
This installs an executable called "linkcore", wherever your Cabal installs user binaries.
====== Running =====
$ cat > hello.hs
module Main where
main = putStrLn "hello world!"
^D
$ linkcore --package-root=$TOP/ghc/libraries --package-root=$TOP/ghc/libraries/base/dist/build --package-root=$TOP/ghc/libraries/integer-gmp hello.hs -o hello_out.hcr
What are all these flags doing? They're telling the Core linker to look for External Core source code in the library
trees you compiled to External Core in an earlier step. Also, the -o flag tells the linker to put the Core output in hello.hcr.
This will take a few minutes and use quite a lot of heap.
Now you can look at the output file hello_out.hcr, manipulate it with the External Core library, etc.
====== More detailed instructions ======
See the HOWTO file in this distribution.
====== Bugs ======
Almost certainly. Please direct bug reports or questions to:
Tim Chevalier <chevalier@alum.wellesley.edu>
