GHC.Driver.Downsweep

ghc-9.14.0.20251028: The GHC API

Safe Haskell | None
Language | GHC2021

GHC.Driver.Downsweep

Contents

- Summary functions
- Helper functions

Synopsis

- downsweep :: HscEnv -> (GhcMessage -> AnyGhcDiagnostic) -> Maybe Messager -> [ModSummary] -> [ModuleName] -> Bool -> IO ([DriverMessages], ModuleGraph)
- downsweepThunk :: HscEnv -> ModSummary -> IO ModuleGraph
- downsweepInstalledModules :: HscEnv -> [Module] -> IO ModuleGraph
- downsweepFromRootNodes :: HscEnv -> Map (UnitId, FilePath) ModSummary -> [ModuleName] -> Bool -> DownsweepMode -> [ModuleNodeInfo] -> [UnitId] -> IO ([DriverMessages], [ModuleGraphNode])
- downsweepInteractiveImports :: HscEnv -> InteractiveContext -> IO ModuleGraph
- data DownsweepMode
  - = DownsweepUseCompile
  - | DownsweepUseFixed
- summariseModule :: HscEnv -> HomeUnit -> Map (UnitId, FilePath) ModSummary -> IsBootInterface -> Located ModuleName -> PkgQual -> Maybe (StringBuffer, UTCTime) -> [ModuleName] -> IO SummariseResult
- summariseFile :: HscEnv -> HomeUnit -> Map (UnitId, FilePath) ModSummary -> FilePath -> Maybe Phase -> Maybe (StringBuffer, UTCTime) -> IO (Either DriverMessages ModSummary)
- summariseModuleInterface :: HscEnv -> HomeUnit -> IsBootInterface -> Located ModuleName -> PkgQual -> [ModuleName] -> IO SummariseResult
- data SummariseResult
  - = FoundInstantiation InstantiatedUnit
  - | FoundHomeWithError (UnitId, DriverMessages)
  - | FoundHome ModuleNodeInfo
  - | External UnitId
  - | NotThere
- instantiationNodes :: UnitId -> UnitState -> [(UnitId, InstantiatedUnit)]
- checkHomeUnitsClosed :: UnitEnv -> [DriverMessages]

# Documentation

downsweep Source #

Arguments

:: HscEnv |
-> (GhcMessage -> AnyGhcDiagnostic) |
-> Maybe Messager |
-> [ModSummary] | Old summaries
-> [ModuleName] |
-> Bool |
-> IO ([DriverMessages], ModuleGraph) |

Downsweep (dependency analysis) for --make mode

Chase downwards from the specified root set, returning summaries for all home modules encountered. Only follow source-import links.

We pass in the previous collection of summaries, which is used as a cache to avoid recalculating a module summary if the source is unchanged.

The returned ModuleGraph has one node for each home-package module, plus one for any hs-boot files. The imports of these nodes are all there, including the imports of non-home-package modules.

This function is intendned for use by --make mode and will also insert LinkNodes and InstantiationNodes for any home units.

It will also turn on code generation for any modules that need it by calling `enableCodeGenForTH`.

downsweepThunk :: HscEnv -> ModSummary -> IO ModuleGraph Source #

Calculate the module graph starting from a single ModSummary. The result is a thunk, which when forced will perform the downsweep. This is useful in oneshot mode where the module graph may never be needed. If downsweep fails, then the resulting errors are just thrown.

downsweepInstalledModules :: HscEnv -> [Module] -> IO ModuleGraph Source #

Create a module graph from a list of installed modules. This is used by the loader when we need to load modules but there isn't already an existing module graph. For example, when loading plugins during initialisation.

If you call this function, then if the `Module` you request to downsweep can't be found then this function will throw errors. If you need to use this function elsewhere, then it would make sense to make it return [DriverMessages] and [ModuleGraph] so that the caller can handle the errors as it sees fit. At the moment, it is overfitted for what `get_reachable_nodes` needs.

downsweepFromRootNodes Source #

Arguments

:: HscEnv |
-> Map (UnitId, FilePath) ModSummary |
-> [ModuleName] |
-> Bool |
-> DownsweepMode | Whether to create fixed or compile nodes for dependencies
-> [ModuleNodeInfo] | The starting ModuleNodeInfo
-> [UnitId] | The starting units
-> IO ([DriverMessages], [ModuleGraphNode]) |

Perform downsweep, starting from the given root `ModuleNodeInfo`s and root `UnitId`s. This function will start at the given roots, and traverse downwards to find all the dependencies, all the way to the leaf units.

downsweepInteractiveImports :: HscEnv -> InteractiveContext -> IO ModuleGraph Source #

Construct a module graph starting from the interactive context. Produces, a thunk, which when forced will perform the downsweep. This graph contains the current interactive module, and its dependencies.

Invariant: The hsc_mod_graph already contains the relevant home modules which might be imported by the interactive imports.

This is a first approximation for this function. There probably should also be edges linking the interactive modules together. (Ie Ghci7 importing Ghci6 and so on) See Note [runTcInteractive module graph]

data DownsweepMode Source #

Whether downsweep should use compiler or fixed nodes. Compile nodes are used by --make mode, and fixed nodes by oneshot mode.

See Note [Module Types in the ModuleGraph] for the difference between the two.

Constructors

DownsweepUseCompile |
DownsweepUseFixed |

# Summary functions

summariseModule :: HscEnv -> HomeUnit -> Map (UnitId, FilePath) ModSummary -> IsBootInterface -> Located ModuleName -> PkgQual -> Maybe (StringBuffer, UTCTime) -> [ModuleName] -> IO SummariseResult Source #

summariseModule finds the location of the source file for the given module. This version always returns a ModuleNodeCompile node, it is useful for --make mode.

summariseFile :: HscEnv -> HomeUnit -> Map (UnitId, FilePath) ModSummary -> FilePath -> Maybe Phase -> Maybe (StringBuffer, UTCTime) -> IO (Either DriverMessages ModSummary) Source #

summariseModuleInterface :: HscEnv -> HomeUnit -> IsBootInterface -> Located ModuleName -> PkgQual -> [ModuleName] -> IO SummariseResult Source #

Like summariseModule but for interface files that we don't want to compile. This version always returns a ModuleNodeFixed node.

data SummariseResult Source #

Constructors

FoundInstantiation InstantiatedUnit |
FoundHomeWithError (UnitId, DriverMessages) |
FoundHome ModuleNodeInfo |
External UnitId |
NotThere |

# Helper functions

instantiationNodes :: UnitId -> UnitState -> [(UnitId, InstantiatedUnit)] Source #

Collect the instantiations of dependencies to create `InstantiationNode` work graph nodes. These are used to represent the type checking that is done after all the free holes (sigs in current package) relevant to that instantiation are compiled. This is necessary to catch some instantiation errors.

checkHomeUnitsClosed :: UnitEnv -> [DriverMessages] Source #

This function checks then important property that if both p and q are home units then any dependency of p, which transitively depends on q is also a home unit.

See Note [Multiple Home Units], section 'Closure Property'.