@hackage linkcore0.4.1

The 'linkcore' program transforms a single Haskell module to a single, closed External Core module.

Previous versions used the GHC API to automatically trace dependencies and build External Core on demand for any intra-package dependencies of the given Haskell module. This was overly complicated (requiring multiple coexisting builds of GHC) and in version 0.4, I eliminated the dependency on the GHC API.

As of version 0.4, this program is a very simple wrapper around the Dependencies and Merge modules of the External Core library. It executes a GHC command, which you can provide as a configure option and which defaults to "ghc", to regenerate Core code if necessary. (Note that as of version 6.10.4, GHC's recompilation checker won't generate .hcr files if the source is older than the .o and .hi files but the .hcr files don't exist. On the other hand, you can pass the --ghc-flag=-fforce-recomp option to linkcore to force GHC to recompile unconditionally.)

===== Prerequisites ====

For the Core Linker to be useful, you will at least need to have built External Core for all the GHC libraries. For more details, see the HOWTO file in this package (henceforth "HOWTO").

You also need to install the extcore package from: http://hackage.haskell.org/package/extcore (or using cabal-install).

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 GHC from source, applying the patches described in HOWTO. (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.

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

Then you do: runhaskell configure --configure-option=--with-ghc=$TOP/ghc

At this stage you can specify zero or more command-line flags to be passed to GHC (when generating Core). After running the configure command, you can look at Config.hs to see the list of flags that was generated. You can also pass extra GHC flags to linkcore itself on the command line.

For example, the command line I would use to configure linkcore is: runhaskell Setup configure --configure-option=--with-ghc=$TOP/ghc/ghc/stage1-inplace/ghc
--configure-option=--ghc-flag=-O2 --configure-option=--ghc-flag=-DSLOW
--configure-option=--ghc-flag=-funfolding-creation-threshold=10
--configure-option=--ghc-flag=-funfolding-use-threshold=10
--configure-option=--ghc-flag=-v0

After that, you do: runhaskell Setup build runhaskell Setup install

like usual. This installs an executable called "linkcore", wherever your Cabal installs executables.

====== 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.

If I want to add another GHC flag, I could say, for example:

$ linkcore --ghc-flag=-O0 --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

This step may be slow. On my machine, reading in all the GHC library files (even just the 61 imported implicitly by the "hello world" program) takes several seconds.

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