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.

3 types
29 values

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

10 declarations

valueue_currentHomeUnitEnv :: HasDebugCallStack => UnitEnv -> HomeUnitEnv

valueue_hpt :: HasDebugCallStack => UnitEnv -> HomePackageTable

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

2 declarations

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

1 declaration

valueassertUnitEnvInvariant :: HasDebugCallStack => UnitEnv -> UnitEnv

Preload units info

2 declarations

valuepreloadUnitsInfo :: UnitEnv -> MaybeErr UnitErr [UnitInfo]

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]

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

1 declaration

valueisUnitEnvInstalledModule :: UnitEnv -> InstalledModule -> Bool

Operations on the UnitEnv

1 declaration

valuerenameUnitId :: 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

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

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

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

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

Queries

0 declarations

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

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

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

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

valuehugAllAnns :: UnitEnv -> IO AnnEnv

Find all the annotations in all home units

Legacy API

1 declaration

This API is deprecated!

valueue_units :: HasDebugCallStack => UnitEnv -> UnitState

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