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

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.