ghc-7.10.2: The GHC API

Safe HaskellNone





defaultErrorHandler :: (ExceptionMonad m, MonadIO m) => FatalMessager -> FlushOut -> m a -> m a Source

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.

defaultCleanupHandler :: (ExceptionMonad m, MonadIO m) => DynFlags -> m a -> m a Source

Install a default cleanup handler to remove temporary files deposited by a GHC run. This is separate from defaultErrorHandler, because you might want to override the error handling, but still get the ordinary cleanup behaviour.

GHC Monad

data Ghc a Source

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.

data GhcT m a Source

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

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

class (Functor m, MonadIO m, ExceptionMonad m, HasDynFlags m) => GhcMonad m where Source

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.


data HscEnv Source

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.

runGhc Source


:: Maybe FilePath

See argument to initGhcMonad.

-> Ghc a

The action to perform.

-> IO a 

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.

runGhcT Source


:: (ExceptionMonad m, Functor m, MonadIO m) 
=> Maybe FilePath

See argument to initGhcMonad.

-> GhcT m a

The action to perform.

-> m a 

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.

initGhcMonad :: GhcMonad m => Maybe FilePath -> m () Source

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

gcatch :: (ExceptionMonad m, Exception e) => m a -> (e -> m a) -> m a Source

Generalised version of catch, allowing an arbitrary exception handling monad instead of just IO.

gbracket :: ExceptionMonad m => m a -> (a -> m b) -> (a -> m c) -> m c Source

Generalised version of bracket, allowing an arbitrary exception handling monad instead of just IO.

gfinally :: ExceptionMonad m => m a -> m b -> m a Source

Generalised version of finally, allowing an arbitrary exception handling monad instead of just IO.

printException :: GhcMonad m => SourceError -> m () Source

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

handleSourceError Source


:: ExceptionMonad m 
=> (SourceError -> m a)

exception handler

-> m a

action to perform

-> m a 

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

needsTemplateHaskell :: ModuleGraph -> Bool Source

Determines whether a set of modules requires Template Haskell.

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.

Flags and settings

data DynFlags Source

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




ghcMode :: GhcMode
ghcLink :: GhcLink
hscTarget :: HscTarget
settings :: Settings
sigOf :: SigOf

Compiling an hs-boot against impl.

verbosity :: Int

Verbosity level: see Note [Verbosity levels]

optLevel :: Int

Optimisation level

simplPhases :: Int

Number of simplifier phases

maxSimplIterations :: Int

Max simplifier iterations

ruleCheck :: Maybe String
strictnessBefore :: [Int]

Additional demand analysis

parMakeCount :: Maybe Int

The number of modules to compile in parallel in --make mode, where Nothing ==> compile as many in parallel as there are CPUs.

enableTimeStats :: Bool

Enable RTS timing statistics?

ghcHeapSize :: Maybe Int

The heap size to set.

maxRelevantBinds :: Maybe Int

Maximum number of bindings from the type envt to show in type error messages

simplTickFactor :: Int

Multiplier for simplifier ticks

specConstrThreshold :: Maybe Int

Threshold for SpecConstr

specConstrCount :: Maybe Int

Max number of specialisations for any one function

specConstrRecursive :: Int

Max number of specialisations for recursive types Not optional; otherwise ForceSpecConstr can diverge.

liberateCaseThreshold :: Maybe Int

Threshold for LiberateCase

floatLamArgs :: Maybe Int

Arg count for lambda floating See CoreMonad.FloatOutSwitches

historySize :: Int
cmdlineHcIncludes :: [String]
importPaths :: [FilePath]
mainModIs :: Module
mainFunIs :: Maybe String
ctxtStkDepth :: Int

Typechecker context stack depth

tyFunStkDepth :: Int

Typechecker type function stack depth

thisPackage :: PackageKey

name of package currently being compiled

ways :: [Way]

Way flags from the command line

buildTag :: String

The global "way" (e.g. "p" for prof)

rtsBuildTag :: String

The RTS "way"

splitInfo :: Maybe (String, Int)
objectDir :: Maybe String
dylibInstallName :: Maybe String
hiDir :: Maybe String
stubDir :: Maybe String
dumpDir :: Maybe String
objectSuf :: String
hcSuf :: String
hiSuf :: String
canGenerateDynamicToo :: IORef Bool
dynObjectSuf :: String
dynHiSuf :: String
dllSplitFile :: Maybe FilePath
dllSplit :: Maybe [Set String]
outputFile :: Maybe String
dynOutputFile :: Maybe String
outputHi :: Maybe String
dynLibLoader :: DynLibLoader
dumpPrefix :: Maybe FilePath

This is set by runPipeline based on where its output is going.

dumpPrefixForce :: Maybe FilePath

Override the dumpPrefix set by runPipeline. Set by -ddump-file-prefix

ldInputs :: [Option]
includePaths :: [String]
libraryPaths :: [String]
frameworkPaths :: [String]
cmdlineFrameworks :: [String]
rtsOpts :: Maybe String
rtsOptsEnabled :: RtsOptsEnabled
hpcDir :: String

Path to store the .mix files

pluginModNames :: [ModuleName]
pluginModNameOpts :: [(ModuleName, String)]
hooks :: Hooks
depMakefile :: FilePath
depIncludePkgDeps :: Bool
depExcludeMods :: [ModuleName]
depSuffixes :: [String]
extraPkgConfs :: [PkgConfRef] -> [PkgConfRef]

The -package-db flags given on the command line, in the order they appeared.

packageFlags :: [PackageFlag]

The -package and -hide-package flags from the command-line

packageEnv :: Maybe FilePath

Filepath to the package environment file (if overriding default)

pkgDatabase :: Maybe [PackageConfig]
pkgState :: PackageState
filesToClean :: IORef [FilePath]
dirsToClean :: IORef (Map FilePath FilePath)
filesToNotIntermediateClean :: IORef [FilePath]
nextTempSuffix :: IORef Int
generatedDumps :: IORef (Set FilePath)
dumpFlags :: IntSet
generalFlags :: IntSet
warningFlags :: IntSet
language :: Maybe Language
safeHaskell :: SafeHaskellMode

Safe Haskell mode

safeInfer :: Bool
safeInferred :: Bool
thOnLoc :: SrcSpan
newDerivOnLoc :: SrcSpan
overlapInstLoc :: SrcSpan
incoherentOnLoc :: SrcSpan
pkgTrustOnLoc :: SrcSpan
warnSafeOnLoc :: SrcSpan
warnUnsafeOnLoc :: SrcSpan
trustworthyOnLoc :: SrcSpan
extensions :: [OnOff ExtensionFlag]
extensionFlags :: IntSet
ufCreationThreshold :: Int
ufUseThreshold :: Int
ufFunAppDiscount :: Int
ufDictDiscount :: Int
ufKeenessFactor :: Float
ufDearOp :: Int
maxWorkerArgs :: Int
ghciHistSize :: Int
log_action :: LogAction

MsgDoc output action: use ErrUtils instead of this if you can

flushOut :: FlushOut
flushErr :: FlushErr
haddockOptions :: Maybe String
ghciScripts :: [String]
pprUserLength :: Int
pprCols :: Int
traceLevel :: Int
useUnicode :: Bool
profAuto :: ProfAuto

what kind of {--} to add automatically

interactivePrint :: Maybe String
llvmVersion :: IORef Int
nextWrapperNum :: IORef (ModuleEnv Int)
sseVersion :: Maybe SseVersion

Machine dependant flags (-mblah stuff)

avx :: Bool
avx2 :: Bool
avx512cd :: Bool
avx512er :: Bool
avx512f :: Bool
avx512pf :: Bool
rtldInfo :: IORef (Maybe LinkerInfo)

Run-time linker information (what options we need, etc.)

rtccInfo :: IORef (Maybe CompilerInfo)

Run-time compiler information

maxInlineAllocSize :: Int

Max size, in bytes, of inline array allocations.

maxInlineMemcpyInsns :: Int

Only inline memcpy if it generates no more than this many pseudo (roughly: Cmm) instructions.

maxInlineMemsetInsns :: Int

Only inline memset if it generates no more than this many pseudo (roughly: Cmm) instructions.

data GeneralFlag Source

Enumerates the simple on-or-off dynamic flags



Append dump output to files instead of stdout.


data HscTarget Source

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 try to run code from an imported module. This will fail if no code has been generated for this module. You can use needsTemplateHaskell to detect whether this might be the case and choose to either switch to a different target or avoid typechecking such modules. (The latter may be preferable for security reasons.)



Generate C code.


Generate assembly using the native code generator.


Generate assembly using the llvm code generator.


Generate bytecode. (Requires LinkInMemory)


Don't generate any code. See notes above.

gopt :: GeneralFlag -> DynFlags -> Bool Source

Test whether a GeneralFlag is set

data GhcMode Source

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



--make, GHCi, etc.

ghc -c Foo.hs

ghc -M, see Finder for why we need this

data GhcLink Source

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



Don't link at all


Link object code into a binary


Use the in-memory dynamic linker (works for both bytecode and object code).


Link objects into a dynamic lib (DLL on Windows, DSO on ELF platforms)


Link objects into a static lib

defaultObjectTarget :: Platform -> HscTarget Source

The HscTarget value corresponding to the default way to create object files on the current platform.

getSessionDynFlags :: GhcMonad m => m DynFlags Source

Grabs the DynFlags from the Session

setSessionDynFlags :: GhcMonad m => DynFlags -> m [PackageKey] Source

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.

getProgramDynFlags :: GhcMonad m => m DynFlags Source

Returns the program DynFlags.

getInteractiveDynFlags :: GhcMonad m => m DynFlags Source

Get the DynFlags used to evaluate interactive expressions.

setInteractiveDynFlags :: GhcMonad m => DynFlags -> m () Source

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 pkgState into the interactive DynFlags.

parseStaticFlags :: [Located String] -> IO ([Located String], [Located String]) Source

Parses GHC's static flags from a list of command line arguments.

These flags are static in the sense that they can be set only once and they are global, meaning that they affect every instance of GHC running; multiple GHC threads will use the same flags.

This function must be called before any session is started, i.e., before the first call to withGhc.

Static flags are more of a hack and are static for more or less historical reasons. In the long run, most static flags should eventually become dynamic flags.

XXX: can we add an auto-generated list of static flags here?


data Target Source

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




targetId :: TargetId

module or filename

targetAllowObjCode :: Bool

object code allowed?

targetContents :: Maybe (StringBuffer, UTCTime)

in-memory text buffer?


data TargetId Source


TargetModule ModuleName

A module name: search for the file

TargetFile FilePath (Maybe Phase)

A filename: preprocess & parse it to find the module name. If specified, the Phase indicates how to compile this file (which phase to start from). Nothing indicates the starting phase should be determined from the suffix of the filename.

setTargets :: GhcMonad m => [Target] -> m () Source

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.

getTargets :: GhcMonad m => m [Target] Source

Returns the current set of targets

addTarget :: GhcMonad m => Target -> m () Source

Add another target.

removeTarget :: GhcMonad m => TargetId -> m () Source

Remove a target

guessTarget :: GhcMonad m => String -> Maybe Phase -> m Target Source

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

Loading/compiling the program

depanal Source


:: GhcMonad m 
=> [ModuleName]

excluded modules

-> Bool

allow duplicate roots

-> m ModuleGraph 

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 to changes to the DynFlags to take effect you need to call this function again.

load :: GhcMonad m => LoadHowMuch -> m SuccessFlag Source

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) compilating and loading may result in files being created on disk.

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

Throw a SourceError if errors are encountered before the actual compilation starts (e.g., during dependency analysis). All other errors are reported using the callback.

data LoadHowMuch Source

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



Load all targets and its dependencies.

LoadUpTo ModuleName

Load only the given module and its dependencies.

LoadDependenciesOf ModuleName

Load only the dependencies of the given module, but not the module itself.

data InteractiveImport Source


IIDecl (ImportDecl RdrName)

Bring the exports of a particular module (filtered by an import decl) into scope

IIModule ModuleName

Bring into scope the entire top-level envt of of this module, including the things imported into it.

type WarnErrLogger = forall m. GhcMonad m => Maybe SourceError -> m () Source

A function called to log warnings and errors.

workingDirectoryChanged :: GhcMonad m => m () Source

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

parseModule :: GhcMonad m => ModSummary -> m ParsedModule Source

Parse a module.

Throws a SourceError on parse error.

typecheckModule :: GhcMonad m => ParsedModule -> m TypecheckedModule Source

Typecheck and rename a parsed module.

Throws a SourceError if either fails.

desugarModule :: GhcMonad m => TypecheckedModule -> m DesugaredModule Source

Desugar a typechecked module.

loadModule :: (TypecheckedMod mod, GhcMonad m) => mod -> m mod Source

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 hscTarget, may also include code generation.

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

data DesugaredModule Source

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

class ParsedMod m where Source

Minimal complete definition

modSummary, parsedSource

coreModule :: DesugaredMod m => m -> ModGuts Source

Compiling to Core

data CoreModule Source

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




cm_module :: !Module

Module name

cm_types :: !TypeEnv

Type environment for types declared in this module

cm_binds :: CoreProgram


cm_safe :: SafeHaskellMode

Safe Haskell mode

compileToCoreModule :: GhcMonad m => FilePath -> m CoreModule Source

This is the way to get access to the Core bindings corresponding to a module. compileToCore parses, typechecks, and desugars the module, then returns the resulting Core module (consisting of the module name, type declarations, and function declarations) if successful.

compileToCoreSimplified :: GhcMonad m => FilePath -> m CoreModule Source

Like compileToCoreModule, but invokes the simplifier, so as to return simplified and tidied Core.

Inspecting the module structure of the program

type ModuleGraph = [ModSummary] Source

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 topSortModuleGraph and flattenSCC to achieve this.

data ModSummary Source

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




ms_mod :: Module

Identity of the module

ms_hsc_src :: HscSource

The module source either plain Haskell, hs-boot or external core

ms_location :: ModLocation

Location of the various files belonging to the module

ms_hs_date :: UTCTime

Timestamp of source file

ms_obj_date :: Maybe UTCTime

Timestamp of object, if we have one

ms_iface_date :: Maybe UTCTime

Timestamp of hi file, if we *only* are typechecking (it is Nothing otherwise. See Note [Recompilation checking when typechecking only] and #9243

ms_srcimps :: [Located (ImportDecl RdrName)]

Source imports of the module

ms_textual_imps :: [Located (ImportDecl RdrName)]

Non-source imports of the module from the module *text*

ms_hspp_file :: FilePath

Filename of preprocessed source file

ms_hspp_opts :: DynFlags

Cached flags from OPTIONS, INCLUDE and LANGUAGE pragmas in the modules source code

ms_hspp_buf :: Maybe StringBuffer

The actual preprocessed source, if we have it

data ModLocation Source

Where a module lives on the file system: the actual locations of the .hs, .hi and .o files, if we have them

getModSummary :: GhcMonad m => ModuleName -> m ModSummary Source

Return the ModSummary of a module with the given name.

The module must be part of the module graph (see hsc_mod_graph and ModuleGraph). If this is not the case, this function will throw a GhcApiError.

This function ignores boot modules and requires that there is only one non-boot module with the given name.

getModuleGraph :: GhcMonad m => m ModuleGraph Source

Get the module dependency graph.

isLoaded :: GhcMonad m => ModuleName -> m Bool Source

Return True == module is loaded.

topSortModuleGraph Source


:: Bool

Drop hi-boot nodes? (see below)

-> [ModSummary] 
-> Maybe ModuleName

Root module name. If Nothing, use the full graph.

-> [SCC ModSummary] 

Topological sort of the module graph

Calculate SCCs of the module graph, possibly dropping the hi-boot nodes The resulting list of strongly-connected-components is in topologically sorted order, starting with the module(s) at the bottom of the dependency graph (ie compile them first) and ending with the ones at the top.

Drop hi-boot nodes (first boolean arg)?

  • False: treat the hi-boot summaries as nodes of the graph, so the graph must be acyclic
  • True: eliminate the hi-boot nodes, and instead pretend the a source-import of Foo is an import of Foo The resulting graph has no hi-boot nodes, but can be cyclic

Inspecting modules

data ModuleInfo Source

Container for information about a Module.

getModuleInfo :: GhcMonad m => Module -> m (Maybe ModuleInfo) Source

Request information about a loaded Module

modInfoTyThings :: ModuleInfo -> [TyThing] Source

The list of top-level entities defined in a module

modInfoInstances :: ModuleInfo -> [ClsInst] Source

Returns the instances defined by the specified module. Warning: currently unimplemented for package modules.

modInfoSafe :: ModuleInfo -> SafeHaskellMode Source

Retrieve module safe haskell mode

lookupGlobalName :: GhcMonad m => Name -> m (Maybe TyThing) Source

Looks up a global name: that is, any top-level name in any visible module. Unlike lookupName, lookupGlobalName does not use the interactive context, and therefore does not require a preceding setContext.

findGlobalAnns :: (GhcMonad m, Typeable a) => ([Word8] -> a) -> AnnTarget Name -> m [a] Source

data ModIface Source

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.




mi_module :: !Module

Name of the module we are for

mi_sig_of :: !(Maybe Module)

Are we a sig of another mod?

mi_iface_hash :: !Fingerprint

Hash of the whole interface

mi_mod_hash :: !Fingerprint

Hash of the ABI only

mi_flag_hash :: !Fingerprint

Hash of the important flags used when compiling this module

mi_orphan :: !WhetherHasOrphans

Whether this module has orphans

mi_finsts :: !WhetherHasFamInst

Whether this module has family instances

mi_boot :: !IsBootInterface

Read from an hi-boot file?

mi_deps :: Dependencies

The dependencies of the module. This is consulted for directly-imported modules, but not for anything else (hence lazy)

mi_usages :: [Usage]

Usages; kept sorted so that it's easy to decide whether to write a new iface file (changing usages doesn't affect the hash of this module) NOT STRICT! we read this field lazily from the interface file It is *only* consulted by the recompilation checker

mi_exports :: ![IfaceExport]

Exports Kept sorted by (mod,occ), to make version comparisons easier Records the modules that are the declaration points for things exported by this module, and the OccNames of those things

mi_exp_hash :: !Fingerprint

Hash of export list

mi_used_th :: !Bool

Module required TH splices when it was compiled. This disables recompilation avoidance (see #481).

mi_fixities :: [(OccName, Fixity)]

Fixities NOT STRICT! we read this field lazily from the interface file

mi_warns :: Warnings

Warnings NOT STRICT! we read this field lazily from the interface file

mi_anns :: [IfaceAnnotation]

Annotations NOT STRICT! we read this field lazily from the interface file

mi_decls :: [(Fingerprint, IfaceDecl)]

Type, class and variable declarations The hash of an Id changes if its fixity or deprecations change (as well as its type of course) Ditto data constructors, class operations, except that the hash of the parent class/tycon changes

mi_globals :: !(Maybe GlobalRdrEnv)

Binds all the things defined at the top level in the original source code for this module. which is NOT the same as mi_exports, nor mi_decls (which may contains declarations for things not actually defined by the user). Used for GHCi and for inspecting the contents of modules via the GHC API only.

(We need the source file to figure out the top-level environment, if we didn't compile this module from source then this field contains Nothing).

Strictly speaking this field should live in the HomeModInfo, but that leads to more plumbing.

mi_insts :: [IfaceClsInst]

Sorted class instance

mi_fam_insts :: [IfaceFamInst]

Sorted family instances

mi_rules :: [IfaceRule]

Sorted rules

mi_orphan_hash :: !Fingerprint

Hash for orphan rules, class and family instances, and vectorise pragmas combined

mi_vect_info :: !IfaceVectInfo

Vectorisation information

mi_warn_fn :: Name -> Maybe WarningTxt

Cached lookup for mi_warns

mi_fix_fn :: OccName -> Fixity

Cached lookup for mi_fixities

mi_hash_fn :: OccName -> Maybe (OccName, Fingerprint)

Cached lookup for mi_decls. The Nothing in mi_hash_fn means that the thing isn't in decls. It's useful to know that when seeing if we are up to date wrt. the old interface. The OccName is the parent of the name, if it has one.

mi_hpc :: !AnyHpcUsage

True if this program uses Hpc at any point in the program.

mi_trust :: !IfaceTrustInfo

Safe Haskell Trust information for this module.

mi_trust_pkg :: !Bool

Do we require the package this module resides in be trusted to trust this module? This is used for the situation where a module is Safe (so doesn't require the package be trusted itself) but imports some trustworthy modules from its own package (which does require its own package be trusted). See Note [RnNames . Trust Own Package]


Querying the environment


data PrintUnqualified Source

When printing code that contains original names, we need to map the original names back to something the user understands. This is the purpose of the triple of functions that gets passed around when rendering SDoc.

Interactive evaluation

getBindings :: GhcMonad m => m [TyThing] Source

Return the bindings for the current interactive session.

getInsts :: GhcMonad m => m ([ClsInst], [FamInst]) Source

Return the instances for the current interactive session.

findModule :: GhcMonad m => ModuleName -> Maybe FastString -> m Module Source

Takes a ModuleName and possibly a PackageKey, and consults the filesystem and package database to find the corresponding Module, using the algorithm that is used for an import declaration.

lookupModule :: GhcMonad m => ModuleName -> Maybe FastString -> m Module Source

Like findModule, but differs slightly when the module refers to a source file, and the file has not been loaded via load. In this case, findModule will throw an error (module not loaded), but lookupModule will check to see whether the module can also be found in a package, and if so, that package Module will be returned. If not, the usual module-not-found error will be thrown.

isModuleTrusted :: GhcMonad m => Module -> m Bool Source

Check that a module is safe to import (according to Safe Haskell).

We return True to indicate the import is safe and False otherwise although in the False case an error may be thrown first.

moduleTrustReqs :: GhcMonad m => Module -> m (Bool, [PackageKey]) Source

Return if a module is trusted and the pkgs it depends on to be trusted.

setContext :: GhcMonad m => [InteractiveImport] -> m () Source

Set the interactive evaluation context.

(setContext imports) sets the ic_imports field (which in turn determines what is in scope at the prompt) to imports, and constructs the ic_rn_glb_env environment to reflect it.

We retain in scope all the things defined at the prompt, and kept in ic_tythings. (Indeed, they shadow stuff from ic_imports.)

getContext :: GhcMonad m => m [InteractiveImport] Source

Get the interactive evaluation context, consisting of a pair of the set of modules from which we take the full top-level scope, and the set of modules from which we take just the exports respectively.

getNamesInScope :: GhcMonad m => m [Name] Source

Returns all names in scope in the current interactive context

getGRE :: GhcMonad m => m GlobalRdrEnv Source

get the GlobalRdrEnv for a session

moduleIsInterpreted :: GhcMonad m => Module -> m Bool Source

Returns True if the specified module is interpreted, and hence has its full top-level scope available.

getInfo :: GhcMonad m => Bool -> Name -> m (Maybe (TyThing, Fixity, [ClsInst], [FamInst])) Source

Looks up an identifier in the current interactive context (for :info) Filter the instances by the ones whose tycons (or clases resp) are in scope (qualified or otherwise). Otherwise we list a whole lot too many! The exact choice of which ones to show, and which to hide, is a judgement call. (see Trac #1581)

exprType :: GhcMonad m => String -> m Type Source

Get the type of an expression Returns its most general type

typeKind :: GhcMonad m => Bool -> String -> m (Type, Kind) Source

Get the kind of a type

parseName :: GhcMonad m => String -> m [Name] Source

Parses a string as an identifier, and returns the list of Names that the identifier can refer to in the current interactive context.

data RunResult Source


RunOk [Name]

names bound by this evaluation

RunException SomeException

statement raised an exception

RunBreak ThreadId [Name] (Maybe BreakInfo) 

runStmt :: GhcMonad m => String -> SingleStep -> m RunResult Source

Run a statement in the current interactive context. Statement may bind multple values.

runStmtWithLocation :: GhcMonad m => String -> Int -> String -> SingleStep -> m RunResult Source

Run a statement in the current interactive context. Passing debug information Statement may bind multple values.

data ModBreaks Source

All the information about the breakpoints for a given module




modBreaks_flags :: BreakArray

The array of flags, one per breakpoint, indicating which breakpoints are enabled.

modBreaks_locs :: !(Array BreakIndex SrcSpan)

An array giving the source span of each breakpoint.

modBreaks_vars :: !(Array BreakIndex [OccName])

An array giving the names of the free variables at each breakpoint.

modBreaks_decls :: !(Array BreakIndex [String])

An array giving the names of the declarations enclosing each breakpoint.

type BreakIndex = Int Source

Breakpoint index

lookupName :: GhcMonad m => Name -> m (Maybe TyThing) Source

Returns the TyThing for a Name. The Name may refer to any entity known to GHC, including Names defined using runStmt.


setGHCiMonad :: GhcMonad m => String -> m () Source

Warning: This is experimental! Don't use.


Set the monad GHCi lifts user statements into.

Checks that a type (in string form) is an instance of the GHC.GHCi.GHCiSandboxIO type class. Sets it to be the GHCi monad if it is, throws an error otherwise.

Abstract syntax elements


data PackageKey Source

A string which uniquely identifies a package. For wired-in packages, it is just the package name, but for user compiled packages, it is a hash. ToDo: when the key is a hash, we can do more clever things than store the hex representation and hash-cons those strings.


data ModuleName Source

A ModuleName is essentially a simple string, e.g. Data.List.


data Name Source

A unique, unambigious name for something, containing information about where that thing originated.

pprParenSymName :: NamedThing a => a -> SDoc Source

print a NamedThing, adding parentheses if the name is an operator.

class NamedThing a where Source

A class allowing convenient access to the Name of various datatypes

Minimal complete definition



getOccName :: a -> OccName Source

getName :: a -> Name Source

data RdrName Source

Do not use the data constructors of RdrName directly: prefer the family of functions that creates them, such as mkRdrUnqual

  • Note: A Located RdrName will only have API Annotations if it is a compound one, e.g.
( ~ )


Unqual OccName

Used for ordinary, unqualified occurrences, e.g. x, y or Foo. Create such a RdrName with mkRdrUnqual

Qual ModuleName OccName

A qualified name written by the user in source code. The module isn't necessarily the module where the thing is defined; just the one from which it is imported. Examples are Bar.x, Bar.y or Bar.Foo. Create such a RdrName with mkRdrQual


type Id = Var Source

isImplicitId :: Id -> Bool Source

isImplicitId tells whether an Ids info is implied by other declarations, so we don't need to put its signature in an interface file, even if it's mentioned in some other interface unfolding.

isExportedId :: Var -> Bool Source

isExportedIdVar means "don't throw this away"

idDataCon :: Id -> DataCon Source

Get from either the worker or the wrapper Id to the DataCon. Currently used only in the desugarer.

INVARIANT: idDataCon (dataConWrapId d) = d: remember, dataConWrapId can return either the wrapper or the worker

isBottomingId :: Id -> Bool Source

Returns true if an application to n args would diverge

recordSelectorFieldLabel :: Id -> (TyCon, FieldLabel) Source

If the Id is that for a record selector, extract the sel_tycon and label. Panic otherwise

Type constructors

data TyCon Source

TyCons represent type constructors. Type constructors are introduced by things such as:

1) Data declarations: data Foo = ... creates the Foo type constructor of kind *

2) Type synonyms: type Foo = ... creates the Foo type constructor

3) Newtypes: newtype Foo a = MkFoo ... creates the Foo type constructor of kind * -> *

4) Class declarations: class Foo where creates the Foo type constructor of kind *

This data type also encodes a number of primitive, built in type constructors such as those for function and tuple types.

tyConTyVars :: TyCon -> [TyVar] Source

The kind and type variables used in the type constructor. Invariant: length tyvars = arity Precisely, this list scopes over:

  1. The algTcStupidTheta
  2. The cached types in algTyConRhs.NewTyCon
  3. The family instance types if present

Note that it does not scope over the data constructors.

tyConDataCons :: TyCon -> [DataCon] Source

As tyConDataCons_maybe, but returns the empty list of constructors if no constructors could be found

tyConArity :: TyCon -> Arity Source

Number of arguments this TyCon must receive to be considered saturated (including implicit kind variables)

isClassTyCon :: TyCon -> Bool Source

Is this TyCon that for a class instance?

isTypeSynonymTyCon :: TyCon -> Bool Source

Is this a TyCon representing a regular H98 type synonym (type)?

isTypeFamilyTyCon :: TyCon -> Bool Source

Is this a synonym TyCon that can have may have further instances appear?

isNewTyCon :: TyCon -> Bool Source

Is this TyCon that for a newtype

isPrimTyCon :: TyCon -> Bool Source

Does this TyCon represent something that cannot be defined in Haskell?

isFamilyTyCon :: TyCon -> Bool Source

Is this a TyCon, synonym or otherwise, that defines a family?

isOpenFamilyTyCon :: TyCon -> Bool Source

Is this a TyCon, synonym or otherwise, that defines a family with instances?

tyConClass_maybe :: TyCon -> Maybe Class Source

If this TyCon is that for a class instance, return the class it is for. Otherwise returns Nothing

synTyConRhs_maybe :: TyCon -> Maybe Type Source

Extract the information pertaining to the right hand side of a type synonym (type) declaration.

synTyConDefn_maybe :: TyCon -> Maybe ([TyVar], Type) Source

Extract the TyVars bound by a vanilla type synonym and the corresponding (unsubstituted) right hand side.

synTyConResKind :: TyCon -> Kind Source

Find the result Kind of a type synonym, after applying it to its arity number of type variables Actually this function works fine on data types too, but they'd always return *, so we never need to ask

Type variables

Data constructors

dataConSig :: DataCon -> ([TyVar], ThetaType, [Type], Type) Source

The "signature" of the DataCon returns, in order:

1) The result of dataConAllTyVars,

2) All the ThetaTypes relating to the DataCon (coercion, dictionary, implicit parameter - whatever)

3) The type arguments to the constructor

4) The original result type of the DataCon

dataConTyCon :: DataCon -> TyCon Source

The type constructor that we are building via this data constructor

dataConFieldLabels :: DataCon -> [FieldLabel] Source

The labels for the fields of this particular DataCon

dataConIsInfix :: DataCon -> Bool Source

Should the DataCon be presented infix?

isVanillaDataCon :: DataCon -> Bool Source

Vanilla DataCons are those that are nice boring Haskell 98 constructors

dataConUserType :: DataCon -> Type Source

The user-declared type of the data constructor in the nice-to-read form:

T :: forall a b. a -> b -> T [a]

rather than:

T :: forall a c. forall b. (c~[a]) => a -> b -> T c

NB: If the constructor is part of a data instance, the result type mentions the family tycon, not the internal one.

dataConSrcBangs :: DataCon -> [HsSrcBang] Source

The strictness markings written by the porgrammer. The list is in one-to-one correspondence with the arity of the DataCon



pprFamInst :: FamInst -> SDoc Source

Pretty-prints a FamInst (type/data family instance) with its defining location.

Types and Kinds

data Type Source

The key representation of types within the compiler


splitForAllTys :: Type -> ([TyVar], Type) Source

Attempts to take a forall type apart, returning all the immediate such bound type variables and the remainder of the type. Always suceeds, even if that means returning an empty list of TyVars

funResultTy :: Type -> Type Source

Extract the function result type and panic if that is not possible

type Kind = Type Source

The key type representing kinds in the compiler. Invariant: a kind is always in one of these forms:

FunTy k1 k2
TyConApp PrimTyCon [...]
TyVar kv   -- (during inference only)
ForAll ... -- (for top-level coercions)

type PredType = Type Source

A type of the form p of kind Constraint represents a value whose type is the Haskell predicate p, where a predicate is what occurs before the => in a Haskell type.

We use PredType as documentation to mark those types that we guarantee to have this kind.

It can be expanded into its representation, but:

  • The type checker must treat it as opaque
  • The rest of the compiler treats it as transparent

Consider these examples:

f :: (Eq a) => a -> Int
g :: (?x :: Int -> Int) => a -> Int
h :: (r\l) => {r} => {l::Int | r}

Here the Eq a and ?x :: Int -> Int and rl are all called "predicates"

type ThetaType = [PredType] Source

A collection of PredTypes


data TyThing Source

A typecheckable-thing, essentially anything that has a name


module HsSyn


Source locations

data RealSrcLoc Source

Represents a single point within a file

noSrcLoc :: SrcLoc Source

Built-in "bad" SrcLoc values for particular locations

srcLocFile :: RealSrcLoc -> FastString Source

Gives the filename of the RealSrcLoc

srcLocLine :: RealSrcLoc -> Int Source

Raises an error when used on a "bad" SrcLoc

srcLocCol :: RealSrcLoc -> Int Source

Raises an error when used on a "bad" SrcLoc

data RealSrcSpan Source

A SrcSpan delimits a portion of a text file. It could be represented by a pair of (line,column) coordinates, but in fact we optimise slightly by using more compact representations for single-line and zero-length spans, both of which are quite common.

The end position is defined to be the column after the end of the span. That is, a span of (1,1)-(1,2) is one character long, and a span of (1,1)-(1,1) is zero characters long.

mkSrcSpan :: SrcLoc -> SrcLoc -> SrcSpan Source

Create a SrcSpan between two points in a file

srcLocSpan :: SrcLoc -> SrcSpan Source

Create a SrcSpan corresponding to a single point

isGoodSrcSpan :: SrcSpan -> Bool Source

Test if a SrcSpan is "good", i.e. has precise location information

noSrcSpan :: SrcSpan Source

Built-in "bad" SrcSpans for common sources of location uncertainty

srcSpanStart :: SrcSpan -> SrcLoc Source

Returns the location at the start of the SrcSpan or a "bad" SrcSpan if that is unavailable

srcSpanEnd :: SrcSpan -> SrcLoc Source

Returns the location at the end of the SrcSpan or a "bad" SrcSpan if that is unavailable


data GenLocated l e Source

We attach SrcSpans to lots of things, so let's have a datatype for it.


L l e 


Constructing Located

noLoc :: e -> Located e Source

Deconstructing Located

unLoc :: GenLocated l e -> e Source

Combining and comparing Located values

eqLocated :: Eq a => Located a -> Located a -> Bool Source

Tests whether the two located things are equal

cmpLocated :: Ord a => Located a -> Located a -> Ordering Source

Tests the ordering of the two located things

addCLoc :: Located a -> Located b -> c -> Located c Source

Combine locations from two Located things and add them to a third thing

leftmost_smallest :: SrcSpan -> SrcSpan -> Ordering Source

Alternative strategies for ordering SrcSpans

leftmost_largest :: SrcSpan -> SrcSpan -> Ordering Source

Alternative strategies for ordering SrcSpans

rightmost :: SrcSpan -> SrcSpan -> Ordering Source

Alternative strategies for ordering SrcSpans

spans :: SrcSpan -> (Int, Int) -> Bool Source

Determines whether a span encloses a given line and column index

isSubspanOf Source


:: SrcSpan

The span that may be enclosed by the other

-> SrcSpan

The span it may be enclosed by

-> Bool 

Determines whether a span is enclosed by another one


data GhcException Source

GHC's own exception type error messages all take the form:

     location: error

If the location is on the command line, or in GHC itself, then location="ghc". All of the error types below correspond to a location of "ghc", except for ProgramError (where the string is assumed to contain a location already, so we don't print one).


PhaseFailed String ExitCode 
Signal Int

Some other fatal signal (SIGHUP,SIGTERM)

UsageError String

Prints the short usage msg after the error

CmdLineError String

A problem with the command line arguments, but don't print usage.

Panic String

The impossible happened.

PprPanic String SDoc 
Sorry String

The user tickled something that's known not to work yet, but we're not counting it as a bug.

PprSorry String SDoc 
InstallationError String

An installation problem.

ProgramError String

An error in the user's code, probably.

PprProgramError String SDoc 

showGhcException :: GhcException -> String -> String Source

Append a description of the given exception to this string.

Token stream manipulations

getTokenStream :: GhcMonad m => Module -> m [Located Token] Source

Return module source as token stream, including comments.

The module must be in the module graph and its source must be available. Throws a SourceError on parse error.

getRichTokenStream :: GhcMonad m => Module -> m [(Located Token, String)] Source

Give even more information on the source than getTokenStream This function allows reconstructing the source completely with showRichTokenStream.

showRichTokenStream :: [(Located Token, String)] -> String Source

Take a rich token stream such as produced from getRichTokenStream and return source code almost identical to the original code (except for insignificant whitespace.)

addSourceToTokens :: RealSrcLoc -> StringBuffer -> [Located Token] -> [(Located Token, String)] Source

Given a source location and a StringBuffer corresponding to this location, return a rich token stream with the source associated to the tokens.

Pure interface to the parser

parser Source


:: String

Haskell module source text (full Unicode is supported)

-> DynFlags

the flags

-> FilePath

the filename (for source locations)

-> Either ErrorMessages (WarningMessages, Located (HsModule RdrName)) 

A pure interface to the module parser.

API Annotations

data AnnKeywordId Source

API Annotations exist so that tools can perform source to source conversions of Haskell code. They are used to keep track of the various syntactic keywords that are not captured in the existing AST.

The annotations, together with original source comments are made available in the pm_annotations field of ParsedModule. Comments are only retained if Opt_KeepRawTokenStream is set in DynFlags before parsing.

The wiki page describing this feature is

Note: in general the names of these are taken from the corresponding token, unless otherwise noted See note [Api annotations] above for details of the usage







case or lambda case


'#)' or '#-}' etc








as a list separator


in a RdrName for a tuple










for function name in matches where there are multiple equations for the function.


for CType


'infix' or 'infixl' or 'infixr'






where a name loses its location in the AST, this carries it


'(#' or '{-# LANGUAGE' etc
























double '''






'()' for types




String value, will need quotes when output












data AnnotationComment Source


AnnDocCommentNext String

something beginning '-- |'

AnnDocCommentPrev String

something beginning '-- ^'

AnnDocCommentNamed String

something beginning '-- $'

AnnDocSection Int String

a section heading

AnnDocOptions String

doc options (prune, ignore-exports, etc)

AnnDocOptionsOld String

doc options declared "-- # ..."-style

AnnLineComment String

comment starting by "--"

AnnBlockComment String

comment in {- -}

getAnnotation :: ApiAnns -> SrcSpan -> AnnKeywordId -> [SrcSpan] Source

Retrieve a list of annotation SrcSpans based on the SrcSpan of the annotated AST element, and the known type of the annotation.

getAndRemoveAnnotation :: ApiAnns -> SrcSpan -> AnnKeywordId -> ([SrcSpan], ApiAnns) Source

Retrieve a list of annotation SrcSpans based on the SrcSpan of the annotated AST element, and the known type of the annotation. The list is removed from the annotations.

getAnnotationComments :: ApiAnns -> SrcSpan -> [Located AnnotationComment] Source

Retrieve the comments allocated to the current SrcSpan

Note: A given SrcSpan may appear in multiple AST elements, beware of duplicates

getAndRemoveAnnotationComments :: ApiAnns -> SrcSpan -> ([Located AnnotationComment], ApiAnns) Source

Retrieve the comments allocated to the current SrcSpan, and remove them from the annotations