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

Safe Haskell | Ignore
Language | GHC2021

GHC.Unit.Env

Contents

- Unit Env helper functions
- HUG Re-export
- Invariants
- Preload units info
- Home Module functions
- Operations on the UnitEnv
  - Modifying the current active home unit
- Queries
  - Queries on the current active home unit
  - Reachability
  - Instances, rules, type fams, annotations, etc..
- Legacy API

Description

A `UnitEnv` provides the complete interface into everything that is loaded into a GHC session, including the `HomeUnitGraph` for mapping home units to their `HomePackageTable`s (which store information about all home modules), and the `ExternalPackageState` which provides access to all external packages loaded.

This module is meant to be imported as `UnitEnv` when calling `insertHpt`:

    import GHC.Unit.Env (UnitEnv, HomeUnitGraph, HomeUnitEnv)
    import GHC.Unit.Env as UnitEnv

Here is an overview of how the UnitEnv, ModuleGraph, HUG, HPT, and EPS interact:

    ┌────────────────┐┌────────────────────┐┌───────────┐
    │HomePackageTable││ExternalPackageState││ModuleGraph│
    └┬───────────────┘└┬───────────────────┘└┬──────────┘
    ┌▽────────────┐    │                     │
    │HomeUnitGraph│    │                     │
    └┬────────────┘    │                     │
    ┌▽─────────────────▽─────────────────────▽┐
    │UnitEnv                                  │
    └┬─────────────-──────────────────────────┘
     │
     │
    ┌▽──────────────────────────────────────▽┐
    │HscEnv                                  │
    └────────────────────────────────────────┘

The `UnitEnv` references the `HomeUnitGraph` (with all the home unit modules), the `ExternalPackageState` (information about all non-home/external units), and the `ModuleGraph` (which describes the relationship between the modules being compiled). The `HscEnv` references this `UnitEnv`. The `HomeUnitGraph` has one `HomePackageTable` for every unit.

Synopsis

- data UnitEnv = UnitEnv {
  - ue_eps :: !ExternalUnitCache
  - ue_current_unit :: UnitId
  - ue_module_graph :: ModuleGraph
  - ue_home_unit_graph :: !HomeUnitGraph
  - ue_platform :: !Platform
  - ue_namever :: !GhcNameVersion
  }
- initUnitEnv :: UnitId -> HomeUnitGraph -> GhcNameVersion -> Platform -> IO UnitEnv
- ueEPS :: UnitEnv -> IO ExternalPackageState
- updateHug :: (HomeUnitGraph -> HomeUnitGraph) -> UnitEnv -> UnitEnv
- ue_currentHomeUnitEnv :: HasDebugCallStack => UnitEnv -> HomeUnitEnv
- ue_hpt :: HasDebugCallStack => UnitEnv -> HomePackageTable
- ue_setActiveUnit :: UnitId -> UnitEnv -> UnitEnv
- ue_currentUnit :: UnitEnv -> UnitId
- ue_findHomeUnitEnv :: HasDebugCallStack => UnitId -> UnitEnv -> HomeUnitEnv
- ue_unitHomeUnit :: UnitId -> UnitEnv -> HomeUnit
- ue_unitHomeUnit_maybe :: UnitId -> UnitEnv -> Maybe HomeUnit
- ue_updateHomeUnitEnv :: (HomeUnitEnv -> HomeUnitEnv) -> UnitId -> UnitEnv -> UnitEnv
- ue_all_home_unit_ids :: UnitEnv -> Set UnitId
- ue_unsafeHomeUnit :: UnitEnv -> HomeUnit
- type HomeUnitGraph = UnitEnvGraph HomeUnitEnv
- data HomeUnitEnv = HomeUnitEnv {
  - homeUnitEnv_units :: !UnitState
  - homeUnitEnv_unit_dbs :: !(Maybe [UnitDatabase UnitId])
  - homeUnitEnv_dflags :: DynFlags
  - homeUnitEnv_hpt :: HomePackageTable
  - homeUnitEnv_home_unit :: !(Maybe HomeUnit)
  }
- assertUnitEnvInvariant :: HasDebugCallStack => UnitEnv -> UnitEnv
- preloadUnitsInfo :: UnitEnv -> MaybeErr UnitErr [UnitInfo]
- preloadUnitsInfo' :: UnitEnv -> [UnitId] -> MaybeErr UnitErr [UnitInfo]
- isUnitEnvInstalledModule :: UnitEnv -> InstalledModule -> Bool
- renameUnitId :: HasDebugCallStack => UnitId -> UnitId -> UnitEnv -> UnitEnv
- insertHpt :: HasDebugCallStack => HomeModInfo -> UnitEnv -> IO ()
- ue_setFlags :: HasDebugCallStack => DynFlags -> UnitEnv -> UnitEnv
- ue_homeUnitState :: HasDebugCallStack => UnitEnv -> UnitState
- ue_unit_dbs :: UnitEnv -> Maybe [UnitDatabase UnitId]
- ue_homeUnit :: UnitEnv -> Maybe HomeUnit
- ue_unitFlags :: HasDebugCallStack => UnitId -> UnitEnv -> DynFlags
- ue_transitiveHomeDeps :: UnitId -> UnitEnv -> [UnitId]
- hugCompleteSigs :: UnitEnv -> IO CompleteMatches
- hugAllInstances :: UnitEnv -> IO (InstEnv, [FamInst])
- hugAllAnns :: UnitEnv -> IO AnnEnv
- ue_units :: HasDebugCallStack => UnitEnv -> UnitState

# Documentation

data UnitEnv #

Constructors

UnitEnv |

Fields

- ue_eps :: !ExternalUnitCache

  Information about the currently loaded external packages. This is mutable because packages will be demand-loaded during a compilation run as required.

- ue_current_unit :: UnitId
- ue_module_graph :: ModuleGraph

  The module graph of the current session See Note [Downsweep and the ModuleGraph] for when this is constructed.

- ue_home_unit_graph :: !HomeUnitGraph
- ue_platform :: !Platform

  Platform

- ue_namever :: !GhcNameVersion

  GHC name/version (used for dynamic library suffix)

initUnitEnv :: UnitId -> HomeUnitGraph -> GhcNameVersion -> Platform -> IO UnitEnv #

ueEPS :: UnitEnv -> IO ExternalPackageState #

updateHug :: (HomeUnitGraph -> HomeUnitGraph) -> UnitEnv -> UnitEnv #

# Unit Env helper functions

ue_currentHomeUnitEnv :: HasDebugCallStack => UnitEnv -> HomeUnitEnv #

ue_hpt :: HasDebugCallStack => UnitEnv -> HomePackageTable #

Get the current home unit's package table

ue_setActiveUnit :: UnitId -> UnitEnv -> UnitEnv #

ue_currentUnit :: UnitEnv -> UnitId #

ue_findHomeUnitEnv :: HasDebugCallStack => UnitId -> UnitEnv -> HomeUnitEnv #

ue_unitHomeUnit :: UnitId -> UnitEnv -> HomeUnit #

ue_unitHomeUnit_maybe :: UnitId -> UnitEnv -> Maybe HomeUnit #

ue_updateHomeUnitEnv :: (HomeUnitEnv -> HomeUnitEnv) -> UnitId -> UnitEnv -> UnitEnv #

ue_all_home_unit_ids :: UnitEnv -> Set UnitId #

ue_unsafeHomeUnit :: UnitEnv -> HomeUnit #

# HUG Re-export

type HomeUnitGraph = UnitEnvGraph HomeUnitEnv #

data HomeUnitEnv #

Constructors

HomeUnitEnv |

Fields

- homeUnitEnv_units :: !UnitState

  External units

- homeUnitEnv_unit_dbs :: !(Maybe [UnitDatabase UnitId])

  Stack of unit databases for the target platform.

  This field is populated with the result of `initUnits`.

  `Nothing` means the databases have never been read from disk.

  Usually we don't reload the databases from disk if they are cached, even if the database flags changed!

- homeUnitEnv_dflags :: DynFlags

  The dynamic flag settings

- homeUnitEnv_hpt :: HomePackageTable

  The home package table describes already-compiled home-package modules, excluding the module we are compiling right now. (In one-shot mode the current module is the only home-package module, so homeUnitEnv_hpt is empty. All other modules count as "external-package" modules. However, even in GHCi mode, hi-boot interfaces are demand-loaded into the external-package table.)

  `homeUnitEnv_hpt` is not mutable because we only demand-load external packages; the home package is eagerly loaded, module by module, by the compilation manager.

  The HPT may contain modules compiled earlier by `--make` but not actually below the current module in the dependency graph.

  (This changes a previous invariant: changed Jan 05.)

- homeUnitEnv_home_unit :: !(Maybe HomeUnit)

  Home-unit

# Invariants

assertUnitEnvInvariant :: HasDebugCallStack => UnitEnv -> UnitEnv #

# Preload units info

preloadUnitsInfo :: UnitEnv -> MaybeErr UnitErr [UnitInfo] #

Lookup `UnitInfo` for every preload unit from the UnitState and for every unit used to instantiate the home unit.

preloadUnitsInfo' :: UnitEnv -> [UnitId] -> MaybeErr UnitErr [UnitInfo] #

Lookup `UnitInfo` for every preload unit from the UnitState, for every unit used to instantiate the home unit, and for every unit explicitly passed in the given list of UnitId.

# Home Module functions

isUnitEnvInstalledModule :: UnitEnv -> InstalledModule -> Bool #

# Operations on the UnitEnv

renameUnitId :: HasDebugCallStack => UnitId -> UnitId -> UnitEnv -> UnitEnv #

Rename a unit id in the internal unit env.

``renameUnitId` oldUnit newUnit UnitEnv`, it is assumed that the `oldUnit` exists in the home units map, otherwise we panic. The `DynFlags` associated with the home unit will have its field `homeUnitId` set to `newUnit`.

## Modifying the current active home unit

insertHpt :: HasDebugCallStack => HomeModInfo -> UnitEnv -> IO () #

Inserts a `HomeModInfo` at the given `ModuleName` on the `HomePackageTable` of the current unit being compiled.

ue_setFlags :: HasDebugCallStack => DynFlags -> UnitEnv -> UnitEnv #

Sets the `DynFlags` of the current unit being compiled to the given ones

# Queries

## Queries on the current active home unit

ue_homeUnitState :: HasDebugCallStack => UnitEnv -> UnitState #

ue_unit_dbs :: UnitEnv -> Maybe [UnitDatabase UnitId] #

ue_homeUnit :: UnitEnv -> Maybe HomeUnit #

ue_unitFlags :: HasDebugCallStack => UnitId -> UnitEnv -> DynFlags #

## Reachability

ue_transitiveHomeDeps :: UnitId -> UnitEnv -> [UnitId] #

## Instances, rules, type fams, annotations, etc..

The `hug` prefix means the function returns only things found in home units.

hugCompleteSigs :: UnitEnv -> IO CompleteMatches #

Get all `CompleteMatches` (arising from COMPLETE pragmas) present across all home units.

hugAllInstances :: UnitEnv -> IO (InstEnv, [FamInst]) #

Find all the instance declarations (of classes and families) from the Home Package Table filtered by the provided predicate function.

hugAllAnns :: UnitEnv -> IO AnnEnv #

Find all the annotations in all home units

# Legacy API

This API is deprecated!

ue_units :: HasDebugCallStack => UnitEnv -> UnitState #

Deprecated: Renamed to ue_homeUnitState because of confusion between units(tate) and unit(s) plural