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 all diagnostics in a SourceError. Useful inside exception handlers.

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

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

Used to describe warnings and errors o The message has a file/line/column heading, plus "warning:" or "error:", added by mkLocMessage o With SevIgnore the message is suppressed o Output is intended for end users

A value of type Backend represents one of GHC's back ends. The set of back ends cannot be extended except by modifying the definition of Backend in this module.

The Backend type is abstract; that is, its value constructors are not exported. It's crucial that they not be exported, because a value of type Backend carries only the back end's name, not its behavior or properties. If Backend were not abstract, then code elsewhere in the compiler could depend directly on the name, not on the semantics, which would make it challenging to create a new back end. Because Backend is abstract, all the obligations of a new back end are enumerated in this module, in the form of functions that take Backend as an argument.

The issue of abstraction is discussed at great length in #20927 and !7442.

Test whether a GeneralFlag is set

Note that dynamicNow (i.e., dynamic objects built with `-dynamic-too`) always implicitly enables Opt_PIC, Opt_ExternalDynamicRefs, and disables Opt_SplitSections.

The native code generator. Compiles Cmm code into textual assembler, then relies on an external assembler toolchain to produce machine code.

Only supports a few platforms (X86, PowerPC, SPARC).

See GHC.CmmToAsm.

The LLVM backend.

Compiles Cmm code into LLVM textual IR, then relies on LLVM toolchain to produce machine code.

It relies on LLVM support for the calling convention used by the NCG backend to produce code objects ABI compatible with it (see "cc 10" or "ghccc" calling convention in https://llvm.org/docs/LangRef.html#calling-conventions).

Supports a few platforms (X86, AArch64, s390x, ARM).

See GHC.CmmToLlvm

Via-C ("unregisterised") backend.

Compiles Cmm code into C code, then relies on a C compiler to produce machine code.

It produces code objects that are not ABI compatible with those produced by NCG and LLVM backends.

Produced code is expected to be less efficient than the one produced by NCG and LLVM backends because STG registers are not pinned into real registers. On the other hand, it supports more target platforms (those having a valid C toolchain).

See GHC.CmmToC

The ByteCode interpreter.

Produce ByteCode objects (BCO, see GHC.ByteCode) that can be interpreted. It is used by GHCi.

Currently some extensions are not supported (foreign primops).

See GHC.StgToByteCode

A dummy back end that generates no code.

Use this back end to disable code generation. It is particularly useful when GHC is used as a library for other purpose than generating code (e.g. to generate documentation with Haddock) or when the user requested it (via `-fno-code`) for some reason.

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

Parse command line arguments that look like files. First normalises its arguments and then splits them into source files and object files. A source file can be turned into a Target via guessTarget

Grabs the DynFlags from the Session

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.

Get the DynFlags used to evaluate interactive expressions.

Set the DynFlags used to evaluate interactive expressions. Also initialise (load) plugins.

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

Push a log hook

Pop a log hook

Push a log hook on the stack

Pop a log hook from the stack

Modify the logger

Put a log message

Put a log message

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

These fields are strict because Targets are long lived.

Untyped Phase description

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 backend (see backend field) 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.

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.