GHC

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.

Sets the program HomeUnitGraph.

Sets the given HomeUnitGraph as the HomeUnitGraph of the current session. If the package flags change, we reinitialise the UnitState of all HomeUnitEnvs in the current session.

This function unconditionally invalidates the module graph cache.

Precondition: the given HomeUnitGraph must have the same keys as the HomeUnitGraph of the current session. I.e., assuming the new HomeUnitGraph is called new_hug, then:

 do
   hug <- hsc_HUG <$> getSession
   pure $ unitEnv_keys new_hug == unitEnv_keys hug

If this precondition is violated, the function will crash.

Conceptually, similar to setProgramDynFlags, but performs the same check for all HomeUnitEnvs.

Same as setProgramHUG, but gives you control over whether you want to invalidate the module graph cache.

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.

Normalise the DynFlags for us in an interactive context.

Makes sure unsupported Flags and other incosistencies are reported and removed.

Given a set of normalised DynFlags (see normaliseInteractiveDynFlags) for the interactive context, initialize the InteractiveContext.

Initialized plugins and sets the DynFlags as the ic_dflags of the InteractiveContext.

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

• If it looks like a module name, interpret it as such

• otherwise, this function throws a GhcException.

Attempts to guess what TargetId 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

• If it looks like a module name, interpret it as such

• otherwise, this function throws a GhcException.

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

How should TcM plugins be handled when initialising of the typechecker? See Note [Stop TcM plugins after desugaring].

Usage:

1. If you want to typecheck then desugar, use StartAndKeepRunningTcMPlugins. This will ensure TcM plugins are kept running for the benefit of the pattern-match checker, and shut down after desugaring.

2. If you only want to typecheck and not desugar, use StartAndStopTcMPlugins.

3. If a prior operation has started TcM plugins, you can use UseRunningTcMPlugins to avoid re-initialising the plugins, for example in initTc.

4. If you don't care about TcM plugins at all, you can use NoTcMPlugins.

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.

Package-qualifier after renaming

Renaming detects if "this" or the unit-id of the home-unit was used as a package qualifier.

A 'ModuleGraph' contains all the nodes from the home package (only). See 'ModuleGraphNode' for information about the nodes.

Modules need to be compiled. hs-boots need to be typechecked before the associated "real" module so modules with {-# SOURCE #-} imports can be built. Instantiations also need to be typechecked to ensure that the module fits the signature. Substantiation typechecking is roughly comparable to the check that the module and its hs-boot agree.

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

Why do we ever need to construct empty graphs? Is it because of one shot mode?

Map a function f over all the ModSummaries. To preserve invariants, f can't change the isBoot status.

Construct a module graph. This function should be the only entry point for building a ModuleGraph, since it is supposed to be built once and never modified.

If you ever find the need to build a ModuleGraph iteratively, don't add insert and update functions to the API since they become footguns. Instead, design an API that allows iterative construction without posterior modification, perhaps like what is done for building arrays from mutable arrays.

Look up a non-boot ModSummary in the ModuleGraph.

Careful: Linear in the size of the module graph MP: This should probably be level aware

Data for a module node in a ModuleGraph. Module nodes of the module graph are one of:

• A regular Haskell source module

• A hi-boot source module

Module Location

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

For a module in another unit, the ml_hs_file_ospath and ml_obj_file_ospath components of ModLocation are undefined.

The locations specified by a ModLocation may or may not correspond to actual files yet: for example, even if the object file doesn't exist, the ModLocation still contains the path to where the object file will reside if/when it is created.

The paths of anything which can affect recompilation should be placed inside ModLocation.

When a ModLocation is created none of the filepaths will have -boot suffixes. This is because in --make mode the ModLocation is put in the finder cache which is indexed by ModuleName, when a ModLocation is retrieved from the FinderCache the boot suffixes are appended. The other case is in -c mode, there the ModLocation immediately gets given the boot suffixes in mkOneShotModLocation.

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.

Get the module dependency graph.

Return True <==> module is loaded.

Check whether a ModuleName is found in the HomePackageTable for the given UnitId.

Check whether Module is part of the HomeUnitGraph.

Similar to isLoadedModule, but for Modules.

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

Container for information about a Module.

Request information about a loaded Module

The list of top-level entities defined in a module

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

Retrieve module safe haskell mode

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.

A ModIface summarises everything we know about a compiled module.

See Note [Structure of ModIface] for information about what belongs in each field.

See Note [Strictness in ModIface] to learn about why all the fields are lazy.

See Note [Private fields in ModIface] to learn why we don't export any of the fields.

The various Safe Haskell modes

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.