ghc-7.10.3: The GHC API

Safe Haskell | None
Language | Haskell2010

HscMain

Contents

- Making an HscEnv
- Compiling complete source files
- Running passes separately
- 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).

Warning messages are dealt with consistently throughout this API: during compilation warnings are collected, and before any function in `HscMain` returns, the warnings are either printed, or turned into a real compialtion error 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
  - | HscUpToDate
  - | HscUpdateBoot
  - | HscUpdateSig
  - | HscRecomp CgGuts ModSummary
- hscCompileOneShot :: HscEnv -> ModSummary -> SourceModified -> IO HscStatus
- hscCompileCmmFile :: HscEnv -> FilePath -> FilePath -> IO ()
- hscCompileCore :: HscEnv -> Bool -> SafeHaskellMode -> ModSummary -> CoreProgram -> FilePath -> IO ()
- genericHscCompileGetFrontendResult :: Bool -> Maybe TcGblEnv -> Maybe Messager -> HscEnv -> ModSummary -> SourceModified -> Maybe ModIface -> (Int, Int) -> IO (Either ModIface (TcGblEnv, Maybe Fingerprint))
- genModDetails :: HscEnv -> ModIface -> IO ModDetails
- hscSimpleIface :: HscEnv -> TcGblEnv -> Maybe Fingerprint -> IO (ModIface, Bool, ModDetails)
- hscWriteIface :: DynFlags -> ModIface -> Bool -> ModSummary -> IO ()
- hscNormalIface :: HscEnv -> ModGuts -> Maybe Fingerprint -> IO (ModIface, Bool, ModDetails, CgGuts)
- hscGenHardCode :: HscEnv -> CgGuts -> ModSummary -> FilePath -> IO (FilePath, Maybe FilePath)
- hscInteractive :: HscEnv -> CgGuts -> ModSummary -> IO (Maybe FilePath, CompiledByteCode, ModBreaks)
- hscParse :: HscEnv -> ModSummary -> IO HsParsedModule
- hscTypecheckRename :: HscEnv -> ModSummary -> HsParsedModule -> IO (TcGblEnv, RenamedStuff)
- hscDesugar :: HscEnv -> ModSummary -> TcGblEnv -> IO ModGuts
- makeSimpleIface :: HscEnv -> Maybe ModIface -> TcGblEnv -> ModDetails -> IO (ModIface, Bool)
- makeSimpleDetails :: HscEnv -> TcGblEnv -> IO ModDetails
- hscSimplify :: HscEnv -> ModGuts -> IO ModGuts
- hscParseIdentifier :: HscEnv -> String -> IO (Located RdrName)
- hscTcRcLookupName :: HscEnv -> Name -> IO (Maybe TyThing)
- hscTcRnGetInfo :: HscEnv -> Name -> IO (Maybe (TyThing, Fixity, [ClsInst], [FamInst]))
- hscCheckSafe :: HscEnv -> Module -> SrcSpan -> IO Bool
- hscGetSafe :: HscEnv -> Module -> SrcSpan -> IO (Bool, [PackageKey])
- hscIsGHCiMonad :: HscEnv -> String -> IO Name
- hscGetModuleInterface :: HscEnv -> Module -> IO ModIface
- hscRnImportDecls :: HscEnv -> [LImportDecl RdrName] -> IO GlobalRdrEnv
- hscTcRnLookupRdrName :: HscEnv -> Located RdrName -> IO [Name]
- hscStmt :: HscEnv -> String -> IO (Maybe ([Id], IO [HValue], FixityEnv))
- hscStmtWithLocation :: HscEnv -> String -> String -> Int -> IO (Maybe ([Id], IO [HValue], FixityEnv))
- hscDecls :: HscEnv -> String -> IO ([TyThing], InteractiveContext)
- hscDeclsWithLocation :: HscEnv -> String -> String -> Int -> IO ([TyThing], InteractiveContext)
- hscTcExpr :: HscEnv -> String -> IO Type
- hscImport :: HscEnv -> String -> IO (ImportDecl RdrName)
- hscKcType :: HscEnv -> Bool -> String -> IO (Type, Kind)
- hscCompileCoreExpr :: HscEnv -> SrcSpan -> CoreExpr -> IO HValue
- hscCompileCoreExpr' :: HscEnv -> SrcSpan -> CoreExpr -> IO HValue
- hscParse' :: ModSummary -> Hsc HsParsedModule
- hscSimplify' :: ModGuts -> Hsc ModGuts
- hscDesugar' :: ModLocation -> TcGblEnv -> Hsc ModGuts
- tcRnModule' :: HscEnv -> ModSummary -> Bool -> HsParsedModule -> Hsc TcGblEnv
- getHscEnv :: Hsc HscEnv
- hscSimpleIface' :: TcGblEnv -> Maybe Fingerprint -> Hsc (ModIface, Bool, ModDetails)
- hscNormalIface' :: ModGuts -> Maybe Fingerprint -> Hsc (ModIface, Bool, ModDetails, CgGuts)
- oneShotMsg :: HscEnv -> RecompileRequired -> IO ()
- hscFileFrontEnd :: ModSummary -> Hsc TcGblEnv
- genericHscFrontend :: ModSummary -> Hsc TcGblEnv
- dumpIfaceStats :: HscEnv -> 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 |
HscUpToDate |
HscUpdateBoot |
HscUpdateSig |
HscRecomp CgGuts ModSummary |

hscCompileOneShot :: HscEnv -> ModSummary -> SourceModified -> IO HscStatus

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

hscCompileCore :: HscEnv -> Bool -> SafeHaskellMode -> ModSummary -> CoreProgram -> FilePath -> IO ()

genericHscCompileGetFrontendResult :: Bool -> Maybe TcGblEnv -> Maybe Messager -> HscEnv -> ModSummary -> SourceModified -> Maybe ModIface -> (Int, Int) -> IO (Either ModIface (TcGblEnv, Maybe Fingerprint))

genModDetails :: HscEnv -> ModIface -> IO ModDetails

hscSimpleIface :: HscEnv -> TcGblEnv -> Maybe Fingerprint -> IO (ModIface, Bool, ModDetails)

hscWriteIface :: DynFlags -> ModIface -> Bool -> ModSummary -> IO ()

hscNormalIface :: HscEnv -> ModGuts -> Maybe Fingerprint -> IO (ModIface, Bool, ModDetails, CgGuts)

hscGenHardCode

Arguments

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

Compile to hard-code.

hscInteractive :: HscEnv -> CgGuts -> ModSummary -> IO (Maybe FilePath, CompiledByteCode, ModBreaks)

# 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

makeSimpleIface :: HscEnv -> Maybe ModIface -> TcGblEnv -> ModDetails -> IO (ModIface, Bool)

Make a `ModIface` from the results of typechecking. Used when not optimising, and the interface doesn't need to contain any unfoldings or other cross-module optimisation info. ToDo: the old interface is only needed to get the version numbers, we should use fingerprint versions instead.

makeSimpleDetails :: HscEnv -> TcGblEnv -> IO ModDetails

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

hscSimplify :: HscEnv -> ModGuts -> IO ModGuts

# 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]))

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, [PackageKey])

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

hscIsGHCiMonad :: HscEnv -> String -> IO Name

hscGetModuleInterface :: HscEnv -> Module -> IO ModIface

hscRnImportDecls :: HscEnv -> [LImportDecl RdrName] -> 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], IO [HValue], 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.

hscStmtWithLocation

Arguments

:: HscEnv |
-> String | The statement
-> String | The source
-> Int | Starting line
-> IO (Maybe ([Id], IO [HValue], 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.

hscDecls

Arguments

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

Compile a decls

hscDeclsWithLocation

Arguments

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

Compile a decls

hscTcExpr

Arguments

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

Typecheck an expression (but don't run it) Returns its most general type

hscImport :: HscEnv -> String -> IO (ImportDecl RdrName)

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 Currently this does *not* generalise the kinds of the type

hscCompileCoreExpr :: HscEnv -> SrcSpan -> CoreExpr -> IO HValue

# Low-level exports for hooks

hscCompileCoreExpr' :: HscEnv -> SrcSpan -> CoreExpr -> IO HValue

hscParse' :: ModSummary -> Hsc HsParsedModule

hscSimplify' :: ModGuts -> Hsc ModGuts

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

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

getHscEnv :: Hsc HscEnv

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

hscNormalIface' :: ModGuts -> Maybe Fingerprint -> Hsc (ModIface, Bool, ModDetails, CgGuts)

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

hscFileFrontEnd :: ModSummary -> Hsc TcGblEnv

genericHscFrontend :: ModSummary -> Hsc TcGblEnv

dumpIfaceStats :: HscEnv -> IO ()