GHC.Unit.Types

A generic module is a pair of a unit identifier and a ModuleName.

A Module is a pair of a Unit and a ModuleName.

A InstalledModule is a Module whose unit is identified with an UnitId.

A HomeUnitModule is like an InstalledModule but we expect to find it in one of the home units rather than the package database.

An InstantiatedModule is a Module whose unit is identified with an InstantiatedUnit.

Calculate the free holes of a Module. If this set is non-empty, this module was defined in an indefinite library that had required signatures.

If a module has free holes, that means that substitutions can operate on it; if it has no free holes, substituting over a module has no effect.

Class for types that are used as unit identifiers (UnitKey, UnitId, Unit)

We need this class because we create new unit ids for virtual units (see VirtUnit) and they have to to be made from units with different kinds of identifiers.

A unit identifier identifies a (possibly partially) instantiated library. It is primarily used as part of Module, which in turn is used in Name, which is used to give names to entities when typechecking.

There are two possible forms for a Unit:

1) It can be a RealUnit, in which case we just have a DefUnitId that uniquely identifies some fully compiled, installed library we have on disk.

2) It can be an VirtUnit. When we are typechecking a library with missing holes, we may need to instantiate a library on the fly (in which case we don't have any on-disk representation.) In that case, you have an InstantiatedUnit, which explicitly records the instantiation, so that we can substitute over it.

A UnitId identifies a built library in a database and is used to generate unique symbols, etc. It's usually of the form:

pkgname-1.2:libname+hash

These UnitId are provided to us via the -this-unit-id flag.

The library in question may be definite or indefinite; if it is indefinite, none of the holes have been filled (we never install partially instantiated libraries as we can cheaply instantiate them on-the-fly, cf VirtUnit). Put another way, an installed unit id is either fully instantiated, or not instantiated at all.

A unit key in the database

An instantiated unit.

It identifies an indefinite library (with holes) that has been instantiated.

This unit may be indefinite or not (i.e. with remaining holes or not). If it is definite, we don't know if it has already been compiled and installed in a database. Nevertheless, we have a mechanism called "improvement" to try to match a fully instantiated unit with existing compiled and installed units: see Note [VirtUnit to RealUnit improvement].

An indefinite unit identifier pretty-prints to something like p[H=H,A=aimpl:A>] (p is the UnitId, and the brackets enclose the module substitution).

A DefUnitId is an UnitId with the invariant that it only refers to a definite library; i.e., one we have generated code for.

Create a new GenInstantiatedUnit given an explicit module substitution.

Generate a uniquely identifying hash (internal unit-id) for an instantiated unit.

This is a one-way function. If the indefinite unit has not been instantiated at all, we return its unit-id.

This hash is completely internal to GHC and is not used for symbol names or file paths. It is different from the hash Cabal would produce for the same instantiated unit.

Smart constructor for instantiated GenUnit

Map over the unit type of a GenUnit

Map over the unit identifier of unit instantiations.

Retrieve the set of free module holes of a Unit.

Create a new simple unit identifier from a FastString. Internally, this is primarily used to specify wired-in unit identifiers.

Return the UnitId of the Unit. For on-the-fly instantiated units, return the UnitId of the indefinite unit this unit is an instance of.

Return the virtual UnitId of an on-the-fly instantiated unit.

Compares unit ids lexically, rather than by their Uniques

A Unit is definite if it has no free holes.

A definite unit (i.e. without any free module hole)

This is the package Id for the current program. It is the default package Id if you don't specify a package name. We don't add this prefix to symbol names, since there can be only one main package per program.

Indicates whether a module name is referring to a boot interface (hs-boot file) or regular module (hs file). We need to treat boot modules specially when building compilation graphs, since they break cycles. Regular source files and signature files are treated equivalently.

This data type just pairs a value mod with an IsBootInterface flag. In practice, mod is usually a Module or ModuleName'.