ghc-8.10.0.20200123: The GHC API

Safe Haskell | None
Language | Haskell2010

Plugins

Contents

- Plugins
  - Recompilation checking
- Plugin types
  - Frontend plugins
  - Core plugins
  - Typechecker plugins
  - Source plugins
  - Hole fit plugins
- Internal

Description

Definitions for writing plugins for GHC. Plugins can hook into several areas of the compiler. See the `Plugin` type. These plugins include type-checker plugins, source plugins, and core-to-core plugins.

Synopsis

- data Plugin = Plugin {
  - installCoreToDos :: CorePlugin
  - tcPlugin :: TcPlugin
  - holeFitPlugin :: HoleFitPlugin
  - dynflagsPlugin :: [CommandLineOption] -> DynFlags -> IO DynFlags
  - pluginRecompile :: [CommandLineOption] -> IO PluginRecompile
  - parsedResultAction :: [CommandLineOption] -> ModSummary -> HsParsedModule -> Hsc HsParsedModule
  - renamedResultAction :: [CommandLineOption] -> TcGblEnv -> HsGroup GhcRn -> TcM (TcGblEnv, HsGroup GhcRn)
  - typeCheckResultAction :: [CommandLineOption] -> ModSummary -> TcGblEnv -> TcM TcGblEnv
  - spliceRunAction :: [CommandLineOption] -> LHsExpr GhcTc -> TcM (LHsExpr GhcTc)
  - interfaceLoadAction :: forall lcl. [CommandLineOption] -> ModIface -> IfM lcl ModIface
  }
- defaultPlugin :: Plugin
- type CommandLineOption = String
- purePlugin :: [CommandLineOption] -> IO PluginRecompile
- impurePlugin :: [CommandLineOption] -> IO PluginRecompile
- flagRecompile :: [CommandLineOption] -> IO PluginRecompile
- data PluginRecompile
  - = ForceRecompile
  - | NoForceRecompile
  - | MaybeRecompile Fingerprint
- data FrontendPlugin = FrontendPlugin {
  - frontend :: FrontendPluginAction
  }
- defaultFrontendPlugin :: FrontendPlugin
- type FrontendPluginAction = [String] -> [(String, Maybe Phase)] -> Ghc ()
- type CorePlugin = [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo]
- type TcPlugin = [CommandLineOption] -> Maybe TcPlugin
- keepRenamedSource :: [CommandLineOption] -> TcGblEnv -> HsGroup GhcRn -> TcM (TcGblEnv, HsGroup GhcRn)
- data HoleFitPluginR
- data PluginWithArgs = PluginWithArgs {
  - paPlugin :: Plugin
  - paArguments :: [CommandLineOption]
  }
- plugins :: DynFlags -> [PluginWithArgs]
- pluginRecompile' :: PluginWithArgs -> IO PluginRecompile
- data LoadedPlugin = LoadedPlugin {
  - lpPlugin :: PluginWithArgs
  - lpModule :: ModIface
  }
- lpModuleName :: LoadedPlugin -> ModuleName
- data StaticPlugin = StaticPlugin {
  - spPlugin :: PluginWithArgs
  }
- mapPlugins :: DynFlags -> (Plugin -> [CommandLineOption] -> a) -> [a]
- withPlugins :: Monad m => DynFlags -> PluginOperation m a -> a -> m a
- withPlugins_ :: Monad m => DynFlags -> ConstPluginOperation m a -> a -> m ()

# Plugins

data Plugin Source #

`Plugin` is the compiler plugin data type. Try to avoid constructing one of these directly, and just modify some fields of `defaultPlugin` instead: this is to try and preserve source-code compatibility when we add fields to this.

Nonetheless, this API is preliminary and highly likely to change in the future.

Constructors

Plugin |
Fields installCoreToDos :: CorePlugin Modify the Core pipeline that will be used for compilation. This is called as the Core pipeline is built for every module being compiled, and plugins get the opportunity to modify the pipeline in a nondeterministic order. tcPlugin :: TcPlugin An optional typechecker plugin, which may modify the behaviour of the constraint solver. holeFitPlugin :: HoleFitPlugin An optional plugin to handle hole fits, which may re-order or change the list of valid hole fits and refinement hole fits. dynflagsPlugin :: [CommandLineOption] -> DynFlags -> IO DynFlags An optional plugin to update `DynFlags`, right after plugin loading. This can be used to register hooks or tweak any field of `DynFlags` before doing actual work on a module. Since: ghc-8.10.1 pluginRecompile :: [CommandLineOption] -> IO PluginRecompile Specify how the plugin should affect recompilation. parsedResultAction :: [CommandLineOption] -> ModSummary -> HsParsedModule -> Hsc HsParsedModule Modify the module when it is parsed. This is called by HscMain when the parsing is successful. renamedResultAction :: [CommandLineOption] -> TcGblEnv -> HsGroup GhcRn -> TcM (TcGblEnv, HsGroup GhcRn) Modify each group after it is renamed. This is called after each `HsGroup` has been renamed. typeCheckResultAction :: [CommandLineOption] -> ModSummary -> TcGblEnv -> TcM TcGblEnv Modify the module when it is type checked. This is called at the very end of typechecking. spliceRunAction :: [CommandLineOption] -> LHsExpr GhcTc -> TcM (LHsExpr GhcTc) Modify the TH splice or quasiqoute before it is run. interfaceLoadAction :: forall lcl. [CommandLineOption] -> ModIface -> IfM lcl ModIface Modify an interface that have been loaded. This is called by LoadIface when an interface is successfully loaded. Not applied to the loading of the plugin interface. Tools that rely on information from modules other than the currently compiled one should implement this function.

defaultPlugin :: Plugin Source #

Default plugin: does nothing at all, except for marking that safe inference has failed unless `-fplugin-trustworthy` is passed. For compatibility reaso you should base all your plugin definitions on this default value.

type CommandLineOption = String Source #

Command line options gathered from the -PModule.Name:stuff syntax are given to you as this type

## Recompilation checking

purePlugin :: [CommandLineOption] -> IO PluginRecompile Source #

impurePlugin :: [CommandLineOption] -> IO PluginRecompile Source #

flagRecompile :: [CommandLineOption] -> IO PluginRecompile Source #

data PluginRecompile Source #

Constructors

ForceRecompile |
NoForceRecompile |
MaybeRecompile Fingerprint |

#### Instances

Instances details

Semigroup PluginRecompile # |
Instance details Defined in Plugins Methods (<>) :: PluginRecompile -> PluginRecompile -> PluginRecompile Source # sconcat :: NonEmpty PluginRecompile -> PluginRecompile Source # stimes :: Integral b => b -> PluginRecompile -> PluginRecompile Source #
Monoid PluginRecompile # |
Instance details Defined in Plugins Methods mempty :: PluginRecompile Source # mappend :: PluginRecompile -> PluginRecompile -> PluginRecompile Source # mconcat :: [PluginRecompile] -> PluginRecompile Source #
Outputable PluginRecompile # |
Instance details Defined in Plugins Methods ppr :: PluginRecompile -> SDoc Source # pprPrec :: Rational -> PluginRecompile -> SDoc Source #

# Plugin types

## Frontend plugins

data FrontendPlugin Source #

Constructors

FrontendPlugin |
Fields frontend :: FrontendPluginAction

defaultFrontendPlugin :: FrontendPlugin Source #

type FrontendPluginAction = [String] -> [(String, Maybe Phase)] -> Ghc () Source #

## Core plugins

Core plugins allow plugins to register as a Core-to-Core pass.

type CorePlugin = [CommandLineOption] -> [CoreToDo] -> CoreM [CoreToDo] Source #

## Typechecker plugins

Typechecker plugins allow plugins to provide evidence to the typechecker.

type TcPlugin = [CommandLineOption] -> Maybe TcPlugin Source #

## Source plugins

GHC offers a number of points where plugins can access and modify its front-end ("source") representation. These include:

- access to the parser result with `parsedResultAction`
- access to the renamed AST with `renamedResultAction`
- access to the typechecked AST with `typeCheckResultAction`
- access to the Template Haskell splices with `spliceRunAction`
- access to loaded interface files with `interfaceLoadAction`

keepRenamedSource :: [CommandLineOption] -> TcGblEnv -> HsGroup GhcRn -> TcM (TcGblEnv, HsGroup GhcRn) Source #

A renamer plugin which mades the renamed source available in a typechecker plugin.

## Hole fit plugins

hole fit plugins allow plugins to change the behavior of valid hole fit suggestions

data HoleFitPluginR Source #

HoleFitPluginR adds a TcRef to hole fit plugins so that plugins can track internal state. Note the existential quantification, ensuring that the state cannot be modified from outside the plugin.

# Internal

data PluginWithArgs Source #

Constructors

PluginWithArgs |
Fields paPlugin :: Plugin the actual callable plugin paArguments :: [CommandLineOption] command line arguments for the plugin

plugins :: DynFlags -> [PluginWithArgs] Source #

pluginRecompile' :: PluginWithArgs -> IO PluginRecompile Source #

data LoadedPlugin Source #

A plugin with its arguments. The result of loading the plugin.

Constructors

LoadedPlugin |
Fields lpPlugin :: PluginWithArgs the actual plugin together with its commandline arguments lpModule :: ModIface the module containing the plugin

lpModuleName :: LoadedPlugin -> ModuleName Source #

data StaticPlugin Source #

A static plugin with its arguments. For registering compiled-in plugins through the GHC API.

Constructors

StaticPlugin |
Fields spPlugin :: PluginWithArgs the actual plugin together with its commandline arguments

mapPlugins :: DynFlags -> (Plugin -> [CommandLineOption] -> a) -> [a] Source #

withPlugins :: Monad m => DynFlags -> PluginOperation m a -> a -> m a Source #

Perform an operation by using all of the plugins in turn.

withPlugins_ :: Monad m => DynFlags -> ConstPluginOperation m a -> a -> m () Source #

Perform a constant operation by using all of the plugins in turn.