ghc-lib-parser-9.10.1.20250103: The GHC API, decoupled from GHC versions

Safe Haskell | Ignore
Language | GHC2021

GHC.Driver.Plugins

Contents

- Plugins
- External plugins
  - Recompilation checking
- Plugin types
  - Frontend plugins
  - Core plugins
  - Typechecker plugins
  - Source plugins
  - Defaulting plugins
  - Hole fit plugins
  - Late 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 Plugins = Plugins {
  - staticPlugins :: ![StaticPlugin]
  - externalPlugins :: ![ExternalPlugin]
  - loadedPlugins :: ![LoadedPlugin]
  - loadedPluginDeps :: !([Linkable], PkgsLoaded)
  }
- emptyPlugins :: Plugins
- data Plugin = Plugin {
  - installCoreToDos :: CorePlugin
  - tcPlugin :: TcPlugin
  - defaultingPlugin :: DefaultingPlugin
  - holeFitPlugin :: HoleFitPlugin
  - driverPlugin :: [CommandLineOption] -> HscEnv -> IO HscEnv
  - latePlugin :: LatePlugin
  - pluginRecompile :: [CommandLineOption] -> IO PluginRecompile
  - parsedResultAction :: [CommandLineOption] -> ModSummary -> ParsedResult -> Hsc ParsedResult
  - 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
- data PsMessages = PsMessages {
  - psWarnings :: Messages PsWarning
  - psErrors :: Messages PsError
  }
- data ParsedResult = ParsedResult {
  - parsedResultModule :: HsParsedModule
  - parsedResultMessages :: PsMessages
  }
- loadExternalPlugins :: [ExternalPluginSpec] -> IO [ExternalPlugin]
- 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)
- type DefaultingPlugin = [CommandLineOption] -> Maybe DefaultingPlugin
- data HoleFitPluginR
- type LatePlugin = HscEnv -> [CommandLineOption] -> (CgGuts, CostCentreState) -> IO (CgGuts, CostCentreState)
- data PluginWithArgs = PluginWithArgs {
  - paPlugin :: Plugin
  - paArguments :: [CommandLineOption]
  }
- pluginsWithArgs :: Plugins -> [PluginWithArgs]
- pluginRecompile' :: PluginWithArgs -> IO PluginRecompile
- data LoadedPlugin = LoadedPlugin {
  - lpPlugin :: PluginWithArgs
  - lpModule :: ModIface
  }
- lpModuleName :: LoadedPlugin -> ModuleName
- data StaticPlugin = StaticPlugin {
  - spPlugin :: PluginWithArgs
  }
- data ExternalPlugin = ExternalPlugin {
  - epPlugin :: PluginWithArgs
  - epUnit :: String
  - epModule :: String
  }
- mapPlugins :: Plugins -> (Plugin -> [CommandLineOption] -> a) -> [a]
- withPlugins :: Monad m => Plugins -> PluginOperation m a -> a -> m a
- withPlugins_ :: Monad m => Plugins -> ConstPluginOperation m a -> a -> m ()

# Plugins

data Plugins #

Constructors

Plugins |

Fields

- staticPlugins :: ![StaticPlugin]

  Static plugins which do not need dynamic loading. These plugins are intended to be added by GHC API users directly to this list.

  To add dynamically loaded plugins through the GHC API see `addPluginModuleName` instead.

- externalPlugins :: ![ExternalPlugin]

  External plugins loaded directly from libraries without loading module interfaces.

- loadedPlugins :: ![LoadedPlugin]

  Plugins dynamically loaded after processing arguments. What will be loaded here is directed by DynFlags.pluginModNames. Arguments are loaded from DynFlags.pluginModNameOpts.

  The purpose of this field is to cache the plugins so they don't have to be loaded each time they are needed. See `initializePlugins`.

- loadedPluginDeps :: !([Linkable], PkgsLoaded)

  The object files required by the loaded plugins See Note [Plugin dependencies]

emptyPlugins :: Plugins #

data Plugin #

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

- defaultingPlugin :: DefaultingPlugin

  An optional defaulting plugin, which may specify the additional type-defaulting rules.

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

- driverPlugin :: [CommandLineOption] -> HscEnv -> IO HscEnv

  An optional plugin to update `HscEnv`, 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: 8.10.1

- latePlugin :: LatePlugin

  A plugin that runs after interface creation and after late cost centre insertion. Useful for transformations that should not impact interfaces or optimization at all.

  Since: 9.10.1

- pluginRecompile :: [CommandLineOption] -> IO PluginRecompile

  Specify how the plugin should affect recompilation.

- parsedResultAction :: [CommandLineOption] -> ModSummary -> ParsedResult -> Hsc ParsedResult

  Modify the module when it is parsed. This is called by GHC.Driver.Main when the parser has produced no or only non-fatal errors. Compilation will fail if the messages produced by this function contain any errors.

- 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 GHC.Iface.Load 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 #

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

type CommandLineOption = String #

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

data PsMessages #

Errors and warnings produced by the parser

Constructors

PsMessages |

Fields

- psWarnings :: Messages PsWarning
- psErrors :: Messages PsError

data ParsedResult #

Result of running the parser and the parser plugin

Constructors

ParsedResult |

Fields

- parsedResultModule :: HsParsedModule

  Parsed module, potentially modified by a plugin

- parsedResultMessages :: PsMessages

  Warnings and errors from parser, potentially modified by a plugin

# External plugins

loadExternalPlugins :: [ExternalPluginSpec] -> IO [ExternalPlugin] #

Load external plugins

## Recompilation checking

purePlugin :: [CommandLineOption] -> IO PluginRecompile #

impurePlugin :: [CommandLineOption] -> IO PluginRecompile #

flagRecompile :: [CommandLineOption] -> IO PluginRecompile #

data PluginRecompile #

Constructors

ForceRecompile |
NoForceRecompile |
MaybeRecompile Fingerprint |

#### Instances

Instances details

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

# Plugin types

## Frontend plugins

data FrontendPlugin #

Constructors

FrontendPlugin |

Fields

- frontend :: FrontendPluginAction

defaultFrontendPlugin :: FrontendPlugin #

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

## Core plugins

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

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

## Typechecker plugins

Typechecker plugins allow plugins to provide evidence to the typechecker.

type TcPlugin = [CommandLineOption] -> Maybe TcPlugin #

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

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

## Defaulting plugins

Defaulting plugins can add candidate types to the defaulting mechanism.

type DefaultingPlugin = [CommandLineOption] -> Maybe DefaultingPlugin #

## Hole fit plugins

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

data HoleFitPluginR #

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.

## Late plugins

Late plugins can access and modify the core of a module after optimizations have been applied and after interface creation.

type LatePlugin = HscEnv -> [CommandLineOption] -> (CgGuts, CostCentreState) -> IO (CgGuts, CostCentreState) #

# Internal

data PluginWithArgs #

Constructors

PluginWithArgs |

Fields

- paPlugin :: Plugin

  the actual callable plugin

- paArguments :: [CommandLineOption]

  command line arguments for the plugin

pluginsWithArgs :: Plugins -> [PluginWithArgs] #

pluginRecompile' :: PluginWithArgs -> IO PluginRecompile #

data LoadedPlugin #

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 #

data StaticPlugin #

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

data ExternalPlugin #

External plugin loaded directly from a library without loading module interfaces

Constructors

ExternalPlugin |

Fields

- epPlugin :: PluginWithArgs

  Plugin with its arguments

- epUnit :: String

  UnitId

- epModule :: String

  Module name

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

withPlugins :: Monad m => Plugins -> PluginOperation m a -> a -> m a #

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

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

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