HscMain

ghc-8.10.2: The GHC API

Safe Haskell | None
Language | Haskell2010

HscMain

Contents

- Making an HscEnv
- Compiling complete source files
- Running passes separately
- Safe Haskell
- Support for interactive evaluation
- Low-level exports for hooks

Description

Main API for compiling plain Haskell source code.

This module implements compilation of a Haskell source. It is not concerned with preprocessing of source files; this is handled in DriverPipeline.

There are various entry points depending on what mode we're in: "batch" mode (`--make`), "one-shot" mode (`-c`, `-S` etc.), and "interactive" mode (GHCi). There are also entry points for individual passes: parsing, typechecking/renaming, desugaring, and simplification.

All the functions here take an `HscEnv` as a parameter, but none of them return a new one: `HscEnv` is treated as an immutable value from here on in (although it has mutable components, for the caches).

We use the Hsc monad to deal with warning messages consistently: specifically, while executing within an Hsc monad, warnings are collected. When a Hsc monad returns to an IO monad, the warnings are printed, or compilation aborts if the `-Werror` flag is enabled.

(c) The GRASP/AQUA Project, Glasgow University, 1993-2000

Synopsis

- newHscEnv :: DynFlags -> IO HscEnv
- type Messager = HscEnv -> (Int, Int) -> RecompileRequired -> ModSummary -> IO ()
- batchMsg :: Messager
- data HscStatus
  - = HscNotGeneratingCode ModIface
  - | HscUpToDate ModIface
  - | HscUpdateBoot ModIface
  - | HscUpdateSig ModIface
  - | HscRecomp {
    - hscs_guts :: CgGuts
    - hscs_mod_location :: !ModLocation
    - hscs_partial_iface :: !PartialModIface
    - hscs_old_iface_hash :: !(Maybe Fingerprint)
    - hscs_iface_dflags :: !DynFlags
    }
- hscIncrementalCompile :: Bool -> Maybe TcGblEnv -> Maybe Messager -> HscEnv -> ModSummary -> SourceModified -> Maybe ModIface -> (Int, Int) -> IO (HscStatus, ModDetails, DynFlags)
- hscMaybeWriteIface :: DynFlags -> ModIface -> Maybe Fingerprint -> ModLocation -> IO ()
- hscCompileCmmFile :: HscEnv -> FilePath -> FilePath -> IO ()
- hscGenHardCode :: HscEnv -> CgGuts -> ModLocation -> FilePath -> IO (FilePath, Maybe FilePath, [(ForeignSrcLang, FilePath)])
- hscInteractive :: HscEnv -> CgGuts -> ModLocation -> IO (Maybe FilePath, CompiledByteCode, [SptEntry])
- hscParse :: HscEnv -> ModSummary -> IO HsParsedModule
- hscTypecheckRename :: HscEnv -> ModSummary -> HsParsedModule -> IO (TcGblEnv, RenamedStuff)
- hscDesugar :: HscEnv -> ModSummary -> TcGblEnv -> IO ModGuts
- makeSimpleDetails :: HscEnv -> TcGblEnv -> IO ModDetails
- hscSimplify :: HscEnv -> [String] -> ModGuts -> IO ModGuts
- hscCheckSafe :: HscEnv -> Module -> SrcSpan -> IO Bool
- hscGetSafe :: HscEnv -> Module -> SrcSpan -> IO (Bool, Set InstalledUnitId)
- hscParseIdentifier :: HscEnv -> String -> IO (Located RdrName)
- hscTcRcLookupName :: HscEnv -> Name -> IO (Maybe TyThing)
- hscTcRnGetInfo :: HscEnv -> Name -> IO (Maybe (TyThing, Fixity, [ClsInst], [FamInst], SDoc))
- hscIsGHCiMonad :: HscEnv -> String -> IO Name
- hscGetModuleInterface :: HscEnv -> Module -> IO ModIface
- hscRnImportDecls :: HscEnv -> [LImportDecl GhcPs] -> IO GlobalRdrEnv
- hscTcRnLookupRdrName :: HscEnv -> Located RdrName -> IO [Name]
- hscStmt :: HscEnv -> String -> IO (Maybe ([Id], ForeignHValue, FixityEnv))
- hscParseStmtWithLocation :: String -> Int -> String -> Hsc (Maybe (GhciLStmt GhcPs))
- hscStmtWithLocation :: HscEnv -> String -> String -> Int -> IO (Maybe ([Id], ForeignHValue, FixityEnv))
- hscParsedStmt :: HscEnv -> GhciLStmt GhcPs -> IO (Maybe ([Id], ForeignHValue, FixityEnv))
- hscDecls :: HscEnv -> String -> IO ([TyThing], InteractiveContext)
- hscParseDeclsWithLocation :: HscEnv -> String -> Int -> String -> IO [LHsDecl GhcPs]
- hscDeclsWithLocation :: HscEnv -> String -> String -> Int -> IO ([TyThing], InteractiveContext)
- hscParsedDecls :: HscEnv -> [LHsDecl GhcPs] -> IO ([TyThing], InteractiveContext)
- hscTcExpr :: HscEnv -> TcRnExprMode -> String -> IO Type
- data TcRnExprMode
  - = TM_Inst
  - | TM_NoInst
  - | TM_Default
- hscImport :: HscEnv -> String -> IO (ImportDecl GhcPs)
- hscKcType :: HscEnv -> Bool -> String -> IO (Type, Kind)
- hscParseExpr :: String -> Hsc (LHsExpr GhcPs)
- hscParseType :: String -> Hsc (LHsType GhcPs)
- hscCompileCoreExpr :: HscEnv -> SrcSpan -> CoreExpr -> IO ForeignHValue
- hscCompileCoreExpr' :: HscEnv -> SrcSpan -> CoreExpr -> IO ForeignHValue
- hscParse' :: ModSummary -> Hsc HsParsedModule
- hscSimplify' :: [String] -> ModGuts -> Hsc ModGuts
- hscDesugar' :: ModLocation -> TcGblEnv -> Hsc ModGuts
- tcRnModule' :: ModSummary -> Bool -> HsParsedModule -> Hsc TcGblEnv
- getHscEnv :: Hsc HscEnv
- hscSimpleIface' :: TcGblEnv -> Maybe Fingerprint -> Hsc (ModIface, Maybe Fingerprint, ModDetails)
- oneShotMsg :: HscEnv -> RecompileRequired -> IO ()
- hscFileFrontEnd :: ModSummary -> Hsc TcGblEnv
- genericHscFrontend :: ModSummary -> Hsc FrontendResult
- dumpIfaceStats :: HscEnv -> IO ()
- ioMsgMaybe :: IO (Messages, Maybe a) -> Hsc a
- showModuleIndex :: (Int, Int) -> String
- hscAddSptEntries :: HscEnv -> [SptEntry] -> IO ()

# Making an HscEnv

newHscEnv :: DynFlags -> IO HscEnv #

# Compiling complete source files

type Messager = HscEnv -> (Int, Int) -> RecompileRequired -> ModSummary -> IO () #

batchMsg :: Messager #

data HscStatus #

Status of a compilation to hard-code

Constructors

HscNotGeneratingCode ModIface | Nothing to do.
HscUpToDate ModIface | Nothing to do because code already exists.
HscUpdateBoot ModIface | Update boot file result.
HscUpdateSig ModIface | Generate signature file (backpack)
HscRecomp | Recompile this module.
Fields hscs_guts :: CgGuts Information for the code generator. hscs_mod_location :: !ModLocation Module info hscs_partial_iface :: !PartialModIface Partial interface hscs_old_iface_hash :: !(Maybe Fingerprint) Old interface hash for this compilation, if an old interface file exists. Pass to `hscMaybeWriteIface` when writing the interface to avoid updating the existing interface when the interface isn't changed. hscs_iface_dflags :: !DynFlags Generate final iface using this DynFlags. FIXME (osa): I don't understand why this is necessary, but I spent almost two days trying to figure this out and I couldn't .. perhaps someone who understands this code better will remove this later.

hscIncrementalCompile :: Bool -> Maybe TcGblEnv -> Maybe Messager -> HscEnv -> ModSummary -> SourceModified -> Maybe ModIface -> (Int, Int) -> IO (HscStatus, ModDetails, DynFlags) #

Used by both OneShot and batch mode. Runs the pipeline HsSyn and Core parts of the pipeline. We return a interface if we already had an old one around and recompilation was not needed. Otherwise it will be created during later passes when we run the compilation pipeline.

hscMaybeWriteIface :: DynFlags -> ModIface -> Maybe Fingerprint -> ModLocation -> IO () #

hscCompileCmmFile :: HscEnv -> FilePath -> FilePath -> IO () #

hscGenHardCode #

Arguments

:: HscEnv |
-> CgGuts |
-> ModLocation |
-> FilePath |
-> IO (FilePath, Maybe FilePath, [(ForeignSrcLang, FilePath)]) | `Just f` = _stub.c is f

Compile to hard-code.

hscInteractive :: HscEnv -> CgGuts -> ModLocation -> IO (Maybe FilePath, CompiledByteCode, [SptEntry]) #

# Running passes separately

hscParse :: HscEnv -> ModSummary -> IO HsParsedModule #

parse a file, returning the abstract syntax

hscTypecheckRename :: HscEnv -> ModSummary -> HsParsedModule -> IO (TcGblEnv, RenamedStuff) #

Rename and typecheck a module, additionally returning the renamed syntax

hscDesugar :: HscEnv -> ModSummary -> TcGblEnv -> IO ModGuts #

Convert a typechecked module to Core

makeSimpleDetails :: HscEnv -> TcGblEnv -> IO ModDetails #

Make a `ModDetails` from the results of typechecking. Used when typechecking only, as opposed to full compilation.

hscSimplify :: HscEnv -> [String] -> ModGuts -> IO ModGuts #

# Safe Haskell

hscCheckSafe :: HscEnv -> Module -> SrcSpan -> IO Bool #

Check that a module is safe to import.

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

hscGetSafe :: HscEnv -> Module -> SrcSpan -> IO (Bool, Set InstalledUnitId) #

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

# Support for interactive evaluation

hscParseIdentifier :: HscEnv -> String -> IO (Located RdrName) #

hscTcRcLookupName :: HscEnv -> Name -> IO (Maybe TyThing) #

hscTcRnGetInfo :: HscEnv -> Name -> IO (Maybe (TyThing, Fixity, [ClsInst], [FamInst], SDoc)) #

hscIsGHCiMonad :: HscEnv -> String -> IO Name #

hscGetModuleInterface :: HscEnv -> Module -> IO ModIface #

hscRnImportDecls :: HscEnv -> [LImportDecl GhcPs] -> IO GlobalRdrEnv #

Rename some import declarations

hscTcRnLookupRdrName :: HscEnv -> Located RdrName -> IO [Name] #

Lookup things in the compiler's environment

hscStmt :: HscEnv -> String -> IO (Maybe ([Id], ForeignHValue, FixityEnv)) #

Compile a stmt all the way to an HValue, but don't run it

We return Nothing to indicate an empty statement (or comment only), not a parse error.

hscParseStmtWithLocation :: String -> Int -> String -> Hsc (Maybe (GhciLStmt GhcPs)) #

hscStmtWithLocation #

Arguments

:: HscEnv |
-> String | The statement
-> String | The source
-> Int | Starting line
-> IO (Maybe ([Id], ForeignHValue, FixityEnv)) |

Compile a stmt all the way to an HValue, but don't run it

We return Nothing to indicate an empty statement (or comment only), not a parse error.

hscParsedStmt #

Arguments

:: HscEnv |
-> GhciLStmt GhcPs | The parsed statement
-> IO (Maybe ([Id], ForeignHValue, FixityEnv)) |

hscDecls #

Arguments

:: HscEnv |
-> String | The statement
-> IO ([TyThing], InteractiveContext) |

Compile a decls

hscParseDeclsWithLocation :: HscEnv -> String -> Int -> String -> IO [LHsDecl GhcPs] #

hscDeclsWithLocation #

Arguments

:: HscEnv |
-> String | The statement
-> String | The source
-> Int | Starting line
-> IO ([TyThing], InteractiveContext) |

Compile a decls

hscParsedDecls :: HscEnv -> [LHsDecl GhcPs] -> IO ([TyThing], InteractiveContext) #

hscTcExpr #

Arguments

:: HscEnv |
-> TcRnExprMode |
-> String | The expression
-> IO Type |

Typecheck an expression (but don't run it)

data TcRnExprMode #

How should we infer a type? See Note [TcRnExprMode]

Constructors

TM_Inst | Instantiate the type fully (:type)
TM_NoInst | Do not instantiate the type (:type +v)
TM_Default | Default the type eagerly (:type +d)

hscImport :: HscEnv -> String -> IO (ImportDecl GhcPs) #

hscKcType #

Arguments

:: HscEnv |
-> Bool | Normalise the type
-> String | The type as a string
-> IO (Type, Kind) | Resulting type (possibly normalised) and kind

Find the kind of a type, after generalisation

hscParseExpr :: String -> Hsc (LHsExpr GhcPs) #

hscParseType :: String -> Hsc (LHsType GhcPs) #

hscCompileCoreExpr :: HscEnv -> SrcSpan -> CoreExpr -> IO ForeignHValue #

# Low-level exports for hooks

hscCompileCoreExpr' :: HscEnv -> SrcSpan -> CoreExpr -> IO ForeignHValue #

hscParse' :: ModSummary -> Hsc HsParsedModule #

hscSimplify' :: [String] -> ModGuts -> Hsc ModGuts #

hscDesugar' :: ModLocation -> TcGblEnv -> Hsc ModGuts #

tcRnModule' :: ModSummary -> Bool -> HsParsedModule -> Hsc TcGblEnv #

getHscEnv :: Hsc HscEnv #

hscSimpleIface' :: TcGblEnv -> Maybe Fingerprint -> Hsc (ModIface, Maybe Fingerprint, ModDetails) #

oneShotMsg :: HscEnv -> RecompileRequired -> IO () #

hscFileFrontEnd :: ModSummary -> Hsc TcGblEnv #

Given a `ModSummary`, parses and typechecks it, returning the `TcGblEnv` resulting from type-checking.

genericHscFrontend :: ModSummary -> Hsc FrontendResult #

dumpIfaceStats :: HscEnv -> IO () #

ioMsgMaybe :: IO (Messages, Maybe a) -> Hsc a #

Deal with errors and warnings returned by a compilation step

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

showModuleIndex :: (Int, Int) -> String #

hscAddSptEntries :: HscEnv -> [SptEntry] -> IO () #

Load the given static-pointer table entries into the interpreter. See Note [Grand plan for static forms] in StaticPtrTable.