Moduleghc-lib-parser-9.14.1.20251220GHC2021

GHC.Unit.Env

A UnitEnv provides the complete interface into everything that is loaded into a GHC session, including the HomeUnitGraph for mapping home units to their HomePackageTables (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.

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

Synopsis

data UnitEnv
value initUnitEnv
value ueEPS
value updateHug
value ue_currentHomeUnitEnv
value ue_hpt
value ue_setActiveUnit
value ue_currentUnit
value ue_findHomeUnitEnv
value ue_unitHomeUnit
value ue_unitHomeUnit_maybe
value ue_updateHomeUnitEnv
value ue_all_home_unit_ids
value ue_unsafeHomeUnit
type HomeUnitGraph
data HomeUnitEnv
value assertUnitEnvInvariant
value preloadUnitsInfo
value preloadUnitsInfo'
value isUnitEnvInstalledModule
value renameUnitId
value insertHpt
value ue_setFlags
value ue_homeUnitState
value ue_unit_dbs
value ue_homeUnit
value ue_unitFlags
value ue_transitiveHomeDeps
value hugCompleteSigs
value hugAllInstances
value hugAllAnns
value ue_units

Packageghc-lib-parser-9.14.1.20251220
Exports32
LanguageGHC2021
LicenceBSD-3-Clause
SourceEnv.hs

datadata UnitEnv

Constructors

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

valueinitUnitEnv

valueueEPS :: UnitEnv -> IO ExternalPackageState

valueupdateHug :: (HomeUnitGraph -> HomeUnitGraph) -> UnitEnv -> UnitEnv

Unit Env helper functions

valueue_currentHomeUnitEnv :: HasDebugCallStack => UnitEnv -> HomeUnitEnv

valueue_hpt :: HasDebugCallStack => UnitEnv -> HomePackageTable

Source#

Get the current home unit's package table

valueue_setActiveUnit :: UnitId -> UnitEnv -> UnitEnv

valueue_currentUnit :: UnitEnv -> UnitId

valueue_findHomeUnitEnv :: HasDebugCallStack => UnitId -> UnitEnv -> HomeUnitEnv

valueue_unitHomeUnit :: UnitId -> UnitEnv -> HomeUnit

valueue_unitHomeUnit_maybe :: UnitId -> UnitEnv -> Maybe HomeUnit

valueue_updateHomeUnitEnv

valueue_all_home_unit_ids :: UnitEnv -> Set UnitId

valueue_unsafeHomeUnit :: UnitEnv -> HomeUnit

HUG Re-export

typetype HomeUnitGraph = UnitEnvGraph HomeUnitEnv

datadata HomeUnitEnv

Constructors

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

valueassertUnitEnvInvariant :: HasDebugCallStack => UnitEnv -> UnitEnv

Preload units info

valuepreloadUnitsInfo :: UnitEnv -> MaybeErr UnitErr [UnitInfo]

Source#

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

valuepreloadUnitsInfo' :: UnitEnv -> [UnitId] -> MaybeErr UnitErr [UnitInfo]

Source#

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

valueisUnitEnvInstalledModule :: UnitEnv -> InstalledModule -> Bool

Operations on the UnitEnv

valuerenameUnitId :: HasDebugCallStack => UnitId -> UnitId -> UnitEnv -> UnitEnv

Source#

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

valueinsertHpt :: HasDebugCallStack => HomeModInfo -> UnitEnv -> IO ()

Source#

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

valueue_setFlags :: HasDebugCallStack => DynFlags -> UnitEnv -> UnitEnv

Source#

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

Queries

Queries on the current active home unit

valueue_homeUnitState :: HasDebugCallStack => UnitEnv -> UnitState

valueue_unit_dbs :: UnitEnv -> Maybe [UnitDatabase UnitId]

valueue_homeUnit :: UnitEnv -> Maybe HomeUnit

valueue_unitFlags :: HasDebugCallStack => UnitId -> UnitEnv -> DynFlags

Reachability

valueue_transitiveHomeDeps :: UnitId -> UnitEnv -> [UnitId]

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

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

valuehugCompleteSigs :: UnitEnv -> IO CompleteMatches

Source#

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

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

Source#

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

valuehugAllAnns :: UnitEnv -> IO AnnEnv

Source#

Find all the annotations in all home units

Legacy API

This API is deprecated!

valueue_units :: HasDebugCallStack => UnitEnv -> UnitState

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