Doing this imports the module GHC from the package ghc. This module exports the "GHC API", which is still in a state of flux. Currently it's not even Haddock-documented. You can see the source code (somewhat documented). There are also other modules of interest as you do more special things.

Here's an example main program that does it Media:Main.hs (good for GHC 6.6). You need to manually change the value of myGhcRoot to point to your GHC directory.

To compile Media:Main.hs, you have to turn on the flag "-package ghc", e.g.

ghc -package ghc Main.hs

2 Common use cases and functions

Assumes GHC 6.6.

2.1 Default exception handling

If you don't handle exceptions yourself, you are recommended to wrap all code inside the wrapper:

2.2 Initialization

The path to your GHC installation directory (e.g., /usr/local/lib/ghc-6.6) is in practice mandatory, even though in theory marked as optional. Also, in 6.8, the type signature of newSession changed to remove the GhcMode (but retaining the still not actually optional Maybe FilePath:

record has a gazillion fields; ask ghci to show all of them. You can change them by hand, or use the parser (which implements the GHC command line format and does the Right Thing). But there are a couple you must note:

The GHC API behaves just like --make: it always links the program if you have a Main module. There are some cases where you will want to turn the linker off; this has the same affect as --make -c. In order to do this, set the ghcLink flag to NoLink:

Dependencies (both modules and packages) are processed automatically, and an executable is produced if appropriate, precisely like --make.

Modules are compiled as per the

hscTarget

flag (-fasm, -fvia-C, or interpreter) in

DynFlags

, independent of GHC mode.

2.4 Compiling to and from Core

Note: the following will only work as advertised in the HEAD (GHC 6.9).

To compile a file to Core (the intermediate language used in GHC's simplifier), call compileToCoreModule:

compileToCoreModule :: Session -> FilePath ->IO(Maybe CoreModule)

compileToCoreModule takes a session and a filename and, if successful, returns a CoreModule corresponding to the Haskell module denoted by the filename. It is not necessary to set a target first.

The CoreModule data type is specified in the HscTypes module in GHC. The most important field is probably cm_binds, a list of Core bindings for all top-level declarations from the original Haskell source file.

For some applications, you may want to compile the Haskell source for various standard libraries into Core. Given the current API, this is probably only possible in the presence of a GHC tree that was built from source, including libraries. (Otherwise, there may be problems finding the right import files.) If you have experience suggesting otherwise, you may wish to report back.

You can also compile Core code to object code:

compileCoreToObj ::Bool-> Session -> CoreModule ->IOBool

compileCoreToObj takes a boolean flag that says whether or not to run the simplifier, a session, and a CoreModule, and returns True iff compilation to machine code succeeded. As a side effect, it creates the executable file, as well as any necessary .hi or .o files, in the current working directory. This has only been tested with a single self-contained Core module (i.e., one that only depends on standard library functions rather than on functions in other user-defined modules).

These functions are a work-in-progress, so if you notice anything that is not what you expect, please complain on the cvs-ghc mailing list or file a bug report.

2.5 Interactive evaluation

Interactive evaluation ala GHCi is done by

runStmt

. But first, this is always done under a current context, i.e., which modules are in scope. Most probably you want to have at least the Prelude and those you loaded in the previous section. How to manipulate the context:

4 Using the GHC library from inside GHCi

This works, to some extent. However, beware about loading object code, because there is only a single linker symbol table in the runtime, so GHCi will be sharing the symbol table with the new GHC session.

5 Profiling

6 Binary size

Using the GHC API in your
applications results in large executables (e.g. > 15Mb). You can mitigate this by an enormous amount using the tools strip and gzexe; this may reduce the executable to 15-30% of its previous size. (Example:

"I will take this time to point out that using the GHC API in your
applications results in *large* executables. The Interact example
above when compiled with vanilla --make options resulted in a whopping
17mb executable. I've observed however you can mitigate this by an
enormous amount using the tools strip and gzexe [see also upx. -ed], taking it down to a light 2.5mb (a size reduction of about 85%)."[1]

(Using 6.8.1 for me results in a 16M binary using the example interactive session from this page, even when thoroughly stripped. Using UPX on its most intensive settings brought it down to 2.9M. --Gwern)