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 GHC.initGhcMonad before any call to the GHC API functions can occur.

A monad that allows logging of warnings.

Lift an IO action returning errors messages into a GhcMonad.

In order to reduce dependencies to other parts of the compiler, functions outside the main parts of GHC return warnings and errors as a parameter and signal success via by wrapping the result in a Maybe type. This function logs the returned warnings and propagates errors as exceptions (of type SourceError).

This function assumes the following invariants:

1. If the second result indicates success (is of the form 'Just x'), there must be no error messages in the first result.
2. If there are no error messages, but the second result indicates failure there should be warnings in the first result. That is, if the action failed, it must have been due to the warnings (i.e., -Werror).

Lift a non-failing IO action into a GhcMonad.

Like ioMsgMaybe, but assumes that the action will never return any error messages.

Clear the log of Warnings.

Returns true if there were any warnings.

A source error is an error that is caused by one or more errors in the source code. A SourceError is thrown by many functions in the compilation pipeline. Inside GHC these errors are merely printed via log_action, but API clients may treat them differently, for example, insert them into a list box. If you want the default behaviour, use the idiom:

 handleSourceError printExceptionAndWarnings $ do
   ... api calls that may fail ...

The SourceErrors error messages can be accessed via srcErrorMessages. This list may be empty if the compiler failed due to -Werror (Opt_WarnIsError).

See printExceptionAndWarnings for more information on what to take care of when writing a custom error handler.

XXX: what exactly is an API error?

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

Reflect a computation in the Ghc monad into the IO monad.

You can use this to call functions returning an action in the Ghc monad inside an IO action. This is needed for some (too restrictive) callback arguments of some library functions:

 libFunc :: String -> (Int -> IO a) -> IO a
 ghcFunc :: Int -> Ghc a

 ghcFuncUsingLibFunc :: String -> Ghc a -> Ghc a
 ghcFuncUsingLibFunc str =
   reifyGhc $ \s ->
     libFunc $ \i -> do
       reflectGhc (ghcFunc i) s

The Session is a handle to the complete state of a compilation session. A compilation session consists of a set of modules constituting the current program or library, the context for interactive evaluation, and various caches.

Call the argument with the current session.

Set the current session to the result of applying the current session to the argument.

Call an action with a temporarily modified Session.

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

The FinderCache maps home module names to the result of searching for that module. It records the results of searching for modules along the search path. On :load, we flush the entire contents of this cache.

Although the FinderCache range is FindResult for convenience , in fact it will only ever contain Found or NotFound entries.

The result of searching for an imported module.

Cache that remembers where we found a particular module. Contains both home modules and package modules. On :load, only home modules are purged from this cache.

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

A ModuleGraph contains all the nodes from the home package (only). There will be a node for each source module, plus a node for each hi-boot module.

The graph is not necessarily stored in topologically-sorted order. Use GHC.topSortModuleGraph and Digraph.flattenSCC to achieve this.

These functions are called in various places of the GHC API.

API clients can override any of these callbacks to change GHC's default behaviour.

Temporarily modify the callbacks. After the action is executed all callbacks are reset (not, however, any other modifications to the session state.)

The ModDetails is essentially a cache for information in the ModIface for home modules only. Information relating to packages will be loaded into global environments in ExternalPackageState.

A ModGuts is carried through the compiler, accumulating stuff as it goes There is only one ModGuts at any time, the one for the module being compiled right now. Once it is compiled, a ModIface and ModDetails are extracted and the ModGuts is dicarded.

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

A restricted form of ModGuts for code generation purposes

Foreign export stubs

Records the modules directly imported by a module for extracting e.g. usage information

A single node in a 'ModuleGraph. The nodes of the module graph are one of:

• A regular Haskell source module
• A hi-boot source module
• An external-core source module

Did this ModSummary originate from a hs-boot file?

Helps us find information about modules in the home package

Information about modules in the package being compiled

Find all the instance declarations (of classes and families) that are in modules imported by this one, directly or indirectly, and are in the Home Package Table. This ensures that we don't see instances from modules --make compiled before this one, but which are not below this one.

Get rules from modules "below" this one (in the dependency sense)

Get the combined VectInfo of all modules in the home package table. In contrast to instances and rules, we don't care whether the modules are "below" us in the dependency sense. The VectInfo of those modules not "below" us does not affect the compilation of the current module.

Information about other packages that we have slurped in by reading their interface files

Accumulated statistics about what we are putting into the ExternalPackageState. "In" means stuff that is just read from interface files, "Out" means actually sucked in and type-checked

Add stats for one newly-read interface

Helps us find information about modules in the imported packages

Find the ModIface for a Module, searching in both the loaded home and external package module information

Deal with gathering annotations in from all possible places and combining them into a single AnnEnv

Interactive context, recording information relevant to GHCi

Creates some functions that work out the best ways to format names for the user according to a set of heuristics

A ModIface plus a ModDetails summarises everything we know about a compiled module. The ModIface is the stuff *before* linking, and can be written out to an interface file. The 'ModDetails is after linking and can be completely recovered from just the ModIface.

When we read an interface file, we also construct a ModIface from it, except that we explicitly make the mi_decls and a few other fields empty; as when reading we consolidate the declarations etc. into a number of indexed maps and environments in the ExternalPackageState.

Constructs the cache for the mi_warn_fn field of a ModIface

Constructs cache for the mi_hash_fn field of a ModIface

Creates cached lookup for the mi_fix_fn field of ModIface

Fixity environment mapping names to their fixities

Fixity information for an Name. We keep the OccName in the range so that we can generate an interface from it

A typecheckable-thing, essentially anything that has a name

Get the Class from a TyThing if it is a class thing. Panics otherwise

Get the TyCon from a TyThing if it is a type constructor thing. Panics otherwise

Get the DataCon from a TyThing if it is a data constructor thing. Panics otherwise

Get the Id from a TyThing if it is a id *or* data constructor thing. Panics otherwise

Determine the TyThings brought into scope by another TyThing other than itself. For example, Id's don't have any implicit TyThings as they just bring themselves into scope, but classes bring their dictionary datatype, type constructor and some selector functions into scope, just for a start!

Returns True if there should be no interface-file declaration for this thing on its own: either it is built-in, or it is part of some other declaration, or it is generated implicitly by some other declaration.

A map from Names to TyThings, constructed by typechecking local declarations or interface files

Find the TyThing for the given Name by using all the resources at our disposal: the compiled modules in the HomePackageTable and the compiled modules in other packages that live in PackageTypeEnv. Note that this does NOT look up the TyThing in the module being compiled: you have to do that yourself, if desired

As lookupType, but with a marginally easier-to-use interface if you have a HscEnv

Class that abstracts out the common ability of the monads in GHC to lookup a TyThing in the monadic environment by Name. Provides a number of related convenience functions for accessing particular kinds of TyThing

Records whether a module has orphans. An "orphan" is one of:

• An instance declaration in a module other than the definition module for one of the type constructors or classes in the instance head
• A transformation rule in a module other than the one defining the function in the head of the rule

Did this module originate from a *-boot file?

Records modules that we depend on by making a direct import from

Dependency information about modules and packages below this one in the import hierarchy.

Invariant: the dependencies of a module M never includes M.

Invariant: none of the lists contain duplicates.

The NameCache makes sure that there is just one Unique assigned for each original name; i.e. (module-name, occ-name) pair and provides something of a lookup mechanism for those names.

Per-module cache of original OccNames given Names

Module-local cache of implicit parameter OccNames given Names

A collection of AvailInfo - several things that are "available"

Just the main name made available, i.e. not the available pieces of type or class brought into scope by the GenAvailInfo

All names made available by the availability information

Records what things are available, i.e. in scope

Named things that are available

RdrNamed things that are available

The original names declared of a certain module that are exported

Warning information for a module

Information we can use to dynamically link modules into the compiler

Objects which have yet to be linked by the compiler

Is this an actual file on disk we can link in somehow?

Retrieve the filename of the linkable if possible. Panic if it is a byte-code object

Is this a bytecode linkable with no file on disk?

Retrieve the compiled byte-code if possible. Panic if it is a file-based linkable

Information about a modules use of Haskell Program Coverage

Find out if HPC is used by this module or any of the modules it depends upon

This is used to signal if one of my imports used HPC instrumentation even if there is no module-local HPC usage

All the information about the breakpoints for a given module

Breakpoint index

Vectorisation information for ModGuts, ModDetails and ExternalPackageState.

Vectorisation information for ModIface: a slightly less low-level view