Install some default exception handlers and run the inner computation. Unless you want to handle exceptions yourself, you should wrap this around the top level of your program. The default handlers output the error message(s) to stderr and exit cleanly.

This function is no longer necessary, cleanup is now done by runGhc/runGhcT.

Temporarily install standard signal handlers for catching ^C, which just throw an exception in the current thread.

A minimal implementation of a GhcMonad. If you need a custom monad, e.g., to maintain additional state consider wrapping this monad or using GhcT.

A monad transformer to add GHC specific features to another monad.

Note that the wrapped monad must support IO and handling of exceptions.

A monad that has all the features needed by GHC API calls.

In short, a GHC monad

• allows embedding of IO actions,
• can log warnings,
• allows handling of (extensible) exceptions, and
• maintains a current session.

If you do not use Ghc or GhcT, make sure to call initGhcMonad before any call to the GHC API functions can occur.

HscEnv is like Session, except that some of the fields are immutable. An HscEnv is used to compile a single module from plain Haskell source code (after preprocessing) to either C, assembly or C--. It's also used to store the dynamic linker state to allow for multiple linkers in the same address space. Things like the module graph don't change during a single compilation.

Historical note: "hsc" used to be the name of the compiler binary, when there was a separate driver and compiler. To compile a single module, the driver would invoke hsc on the source code... so nowadays we think of hsc as the layer of the compiler that deals with compiling a single module.

Run function for the Ghc monad.

It initialises the GHC session and warnings via initGhcMonad. Each call to this function will create a new session which should not be shared among several threads.

Any errors not handled inside the Ghc action are propagated as IO exceptions.

Run function for GhcT monad transformer.

It initialises the GHC session and warnings via initGhcMonad. Each call to this function will create a new session which should not be shared among several threads.

Initialise a GHC session.

If you implement a custom GhcMonad you must call this function in the monad run function. It will initialise the session variable and clear all warnings.

The first argument should point to the directory where GHC's library files reside. More precisely, this should be the output of ghc --print-libdir of the version of GHC the module using this API is compiled with. For portability, you should use the ghc-paths package, available at http://hackage.haskell.org/package/ghc-paths.

Print the error message and all warnings. Useful inside exception handlers. Clears warnings after printing.

Perform the given action and call the exception handler if the action throws a SourceError. See SourceError for more information.

Determines whether a set of modules requires Template Haskell or Quasi Quotes

Note that if the session's DynFlags enabled Template Haskell when depanal was called, then each module in the returned module graph will have Template Haskell enabled whether it is actually needed or not.

Contains not only a collection of GeneralFlags but also a plethora of information relating to the compilation of a single file or GHC session

Enumerates the simple on-or-off dynamic flags

The target code type of the compilation (if any).

Whenever you change the target, also make sure to set ghcLink to something sensible.

HscNothing can be used to avoid generating any output, however, note that:

• If a program uses Template Haskell the typechecker may need to run code from an imported module. To facilitate this, code generation is enabled for modules imported by modules that use template haskell. See Note [-fno-code mode].

Test whether a GeneralFlag is set

The GhcMode tells us whether we're doing multi-module compilation (controlled via the GHC API) or one-shot (single-module) compilation. This makes a difference primarily to the GHC.Driver.Finder: in one-shot mode we look for interface files for imported modules, but in multi-module mode we look for source files in order to check whether they need to be recompiled.

What to do in the link step, if there is one.

Grabs the DynFlags from the Session

Updates both the interactive and program DynFlags in a Session. This also reads the package database (unless it has already been read), and prepares the compilers knowledge about packages. It can be called again to load new packages: just add new package flags to (packageFlags dflags).

Returns a list of new packages that may need to be linked in using the dynamic linker (see linkPackages) as a result of new package flags. If you are not doing linking or doing static linking, you can ignore the list of packages returned.

Returns the program DynFlags.

Sets the program DynFlags. Note: this invalidates the internal cached module graph, causing more work to be done the next time load is called.

Returns a boolean indicating if preload units have changed and need to be reloaded.

Set the action taken when the compiler produces a message. This can also be accomplished using setProgramDynFlags, but using setLogAction avoids invalidating the cached module graph.

Get the DynFlags used to evaluate interactive expressions.

Set the DynFlags used to evaluate interactive expressions. Note: this cannot be used for changes to packages. Use setSessionDynFlags, or setProgramDynFlags and then copy the unitState into the interactive DynFlags.

Find the package environment (if one exists)

We interpret the package environment as a set of package flags; to be specific, if we find a package environment file like

clear-package-db
global-package-db
package-db blah/package.conf.d
package-id id1
package-id id2

we interpret this as

[ -hide-all-packages
, -clear-package-db
, -global-package-db
, -package-db blah/package.conf.d
, -package-id id1
, -package-id id2
]

There's also an older syntax alias for package-id, which is just an unadorned package id

id1
id2

A compilation target.

A target may be supplied with the actual text of the module. If so, use this instead of the file contents (this is for use in an IDE where the file hasn't been saved by the user yet).

Sets the targets for this session. Each target may be a module name or a filename. The targets correspond to the set of root modules for the program/library. Unloading the current program is achieved by setting the current set of targets to be empty, followed by load.

Returns the current set of targets

Add another target.

Remove a target

Attempts to guess what Target a string refers to. This function implements the --make/GHCi command-line syntax for filenames:

• if the string looks like a Haskell source filename, then interpret it as such
• if adding a .hs or .lhs suffix yields the name of an existing file, then use that
• otherwise interpret the string as a module name

Perform a dependency analysis starting from the current targets and update the session with the new module graph.

Dependency analysis entails parsing the import directives and may therefore require running certain preprocessors.

Note that each ModSummary in the module graph caches its DynFlags. These DynFlags are determined by the current session DynFlags and the OPTIONS and LANGUAGE pragmas of the parsed module. Thus if you want changes to the DynFlags to take effect you need to call this function again. In case of errors, just throw them.

Perform dependency analysis like in depanal. In case of errors, the errors and an empty module graph are returned.

Try to load the program. See LoadHowMuch for the different modes.

This function implements the core of GHC's --make mode. It preprocesses, compiles and loads the specified modules, avoiding re-compilation wherever possible. Depending on the target (see hscTarget) compiling and loading may result in files being created on disk.

Calls the defaultWarnErrLogger after each compiling each module, whether successful or not.

If errors are encountered during dependency analysis, the module depanalE returns together with the errors an empty ModuleGraph. After processing this empty ModuleGraph, the errors of depanalE are thrown. All other errors are reported using the defaultWarnErrLogger.

Describes which modules of the module graph need to be loaded.

A function called to log warnings and errors.

Inform GHC that the working directory has changed. GHC will flush its cache of module locations, since it may no longer be valid.

Note: Before changing the working directory make sure all threads running in the same session have stopped. If you change the working directory, you should also unload the current program (set targets to empty, followed by load).

Parse a module.

Throws a SourceError on parse error.

Typecheck and rename a parsed module.

Throws a SourceError if either fails.

Desugar a typechecked module.

Load a module. Input doesn't need to be desugared.

A module must be loaded before dependent modules can be typechecked. This always includes generating a ModIface and, depending on the DynFlags's hscTarget, may also include code generation.

This function will always cause recompilation and will always overwrite previous compilation results (potentially files on disk).

The result of successful parsing.

The result of successful typechecking. It also contains the parser result.

The result of successful desugaring (i.e., translation to core). Also contains all the information of a typechecked module.

A CoreModule consists of just the fields of a ModGuts that are needed for the compileToCoreModule interface.