GHC.Linker.Types

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

Safe Haskell | Ignore
Language | GHC2021

GHC.Linker.Types

Contents

- Linkable

Synopsis

- newtype Loader = Loader {
  - loader_state :: MVar (Maybe LoaderState)
  }
- data LoaderState = LoaderState {
  - linker_env :: !LinkerEnv
  - bcos_loaded :: !LinkableSet
  - objs_loaded :: !LinkableSet
  - pkgs_loaded :: !PkgsLoaded
  - temp_sos :: ![(FilePath, String)]
  - linked_breaks :: !LinkedBreaks
  }
- uninitializedLoader :: IO Loader
- modifyClosureEnv :: LoaderState -> (ClosureEnv -> ClosureEnv) -> LoaderState
- data LinkerEnv = LinkerEnv {
  - closure_env :: !ClosureEnv
  - itbl_env :: !ItblEnv
  - addr_env :: !AddrEnv
  }
- filterLinkerEnv :: (Name -> Bool) -> LinkerEnv -> LinkerEnv
- type ClosureEnv = NameEnv (Name, ForeignHValue)
- emptyClosureEnv :: ClosureEnv
- extendClosureEnv :: ClosureEnv -> [(Name, ForeignHValue)] -> ClosureEnv
- data LinkedBreaks = LinkedBreaks {
  - breakarray_env :: !(ModuleEnv (ForeignRef BreakArray))
  - ccs_env :: !(ModuleEnv (Array BreakTickIndex (RemotePtr CostCentre)))
  }
- filterLinkedBreaks :: (Module -> Bool) -> LinkedBreaks -> LinkedBreaks
- type LinkableSet = ModuleEnv Linkable
- mkLinkableSet :: [Linkable] -> LinkableSet
- unionLinkableSet :: LinkableSet -> LinkableSet -> LinkableSet
- type ObjFile = FilePath
- data SptEntry = SptEntry Id Fingerprint
- data LibrarySpec
  - = Objects [FilePath]
  - | Archive FilePath
  - | DLL String
  - | DLLPath FilePath
  - | Framework String
- data LoadedPkgInfo = LoadedPkgInfo {
  - loaded_pkg_uid :: !UnitId
  - loaded_pkg_hs_objs :: ![LibrarySpec]
  - loaded_pkg_non_hs_objs :: ![LibrarySpec]
  - loaded_pkg_hs_dlls :: ![RemotePtr LoadedDLL]
  - loaded_pkg_trans_deps :: UniqDSet UnitId
  }
- type PkgsLoaded = UniqDFM UnitId LoadedPkgInfo
- data Linkable = Linkable {
  - linkableTime :: !UTCTime
  - linkableModule :: !Module
  - linkableParts :: NonEmpty LinkablePart
  }
- data LinkablePart
  - = DotO ObjFile LinkableObjectSort
  - | DotA FilePath
  - | DotDLL FilePath
  - | CoreBindings WholeCoreBindings
  - | LazyBCOs CompiledByteCode [FilePath]
  - | BCOs CompiledByteCode
- data LinkableObjectSort
  - = ModuleObject
  - | ForeignObject
- linkableIsNativeCodeOnly :: Linkable -> Bool
- linkableObjs :: Linkable -> [FilePath]
- linkableLibs :: Linkable -> [LinkablePart]
- linkableFiles :: Linkable -> [FilePath]
- linkableBCOs :: Linkable -> [CompiledByteCode]
- linkableNativeParts :: Linkable -> [LinkablePart]
- linkablePartitionParts :: Linkable -> ([LinkablePart], [LinkablePart])
- linkablePartPath :: LinkablePart -> Maybe FilePath
- linkablePartAllBCOs :: LinkablePart -> [CompiledByteCode]
- isNativeCode :: LinkablePart -> Bool
- isNativeLib :: LinkablePart -> Bool
- linkableFilterByteCode :: Linkable -> Maybe Linkable
- linkableFilterNative :: Linkable -> Maybe Linkable
- partitionLinkables :: [Linkable] -> ([Linkable], [Linkable])

# Documentation

newtype Loader #

Constructors

Loader |
Fields loader_state :: MVar (Maybe LoaderState)

data LoaderState #

Constructors

LoaderState |
Fields linker_env :: !LinkerEnv Current global mapping from Names to their true values bcos_loaded :: !LinkableSet The currently loaded interpreted modules (home package) objs_loaded :: !LinkableSet And the currently-loaded compiled modules (home package) pkgs_loaded :: !PkgsLoaded The currently-loaded packages; always object code haskell libraries, system libraries, transitive dependencies temp_sos :: ![(FilePath, String)] We need to remember the name of previous temporary DLL/.so libraries so we can link them (see #10322) linked_breaks :: !LinkedBreaks Mapping from loaded modules to their breakpoint arrays

uninitializedLoader :: IO Loader #

modifyClosureEnv :: LoaderState -> (ClosureEnv -> ClosureEnv) -> LoaderState #

data LinkerEnv #

Constructors

LinkerEnv |
Fields closure_env :: !ClosureEnv Current global mapping from closure Names to their true values itbl_env :: !ItblEnv The current global mapping from RdrNames of DataCons to info table addresses. When a new LinkablePart is linked into the running image, or an existing module in the image is replaced, the itbl_env must be updated appropriately. addr_env :: !AddrEnv Like `closure_env` and `itbl_env`, but for top-level 'Addr#' literals, see Note [Generating code for top-level string literal bindings] in GHC.StgToByteCode.

filterLinkerEnv :: (Name -> Bool) -> LinkerEnv -> LinkerEnv #

type ClosureEnv = NameEnv (Name, ForeignHValue) #

emptyClosureEnv :: ClosureEnv #

extendClosureEnv :: ClosureEnv -> [(Name, ForeignHValue)] -> ClosureEnv #

data LinkedBreaks #

`BreakArray`s and CCSs are allocated per-module at link-time.

Specifically, a module's `BreakArray` is allocated either: - When a BCO for that module is linked - When :break is used on a given module *before* the BCO has been linked.

We keep this structure in the `LoaderState`

Constructors

LinkedBreaks |
Fields breakarray_env :: !(ModuleEnv (ForeignRef BreakArray)) Each `Module`s remote pointer of `BreakArray`. ccs_env :: !(ModuleEnv (Array BreakTickIndex (RemotePtr CostCentre))) Each `Module`s array of remote pointers of `CostCentre`. Untouched when not profiling.

filterLinkedBreaks :: (Module -> Bool) -> LinkedBreaks -> LinkedBreaks #

type LinkableSet = ModuleEnv Linkable #

mkLinkableSet :: [Linkable] -> LinkableSet #

unionLinkableSet :: LinkableSet -> LinkableSet -> LinkableSet #

Union of LinkableSets.

In case of conflict, keep the most recent Linkable (as per linkableTime)

type ObjFile = FilePath #

data SptEntry #

An entry to be inserted into a module's static pointer table. See Note [Grand plan for static forms] in GHC.Iface.Tidy.StaticPtrTable.

Constructors

SptEntry Id Fingerprint |

#### Instances

Instances details

Outputable SptEntry # |
Instance details Defined in GHC.Types.SptEntry Methods ppr :: SptEntry -> SDoc #

data LibrarySpec #

Constructors

Objects [FilePath] |
Archive FilePath |
DLL String |
DLLPath FilePath |
Framework String |

#### Instances

Instances details

Outputable LibrarySpec # |
Instance details Defined in GHC.Linker.Types Methods ppr :: LibrarySpec -> SDoc #

data LoadedPkgInfo #

Constructors

LoadedPkgInfo |
Fields loaded_pkg_uid :: !UnitId loaded_pkg_hs_objs :: ![LibrarySpec] loaded_pkg_non_hs_objs :: ![LibrarySpec] loaded_pkg_hs_dlls :: ![RemotePtr LoadedDLL] See Note [Looking up symbols in the relevant objects] loaded_pkg_trans_deps :: UniqDSet UnitId

#### Instances

Instances details

Outputable LoadedPkgInfo # |
Instance details Defined in GHC.Linker.Types Methods ppr :: LoadedPkgInfo -> SDoc #

type PkgsLoaded = UniqDFM UnitId LoadedPkgInfo #

# Linkable

data Linkable #

Information we can use to dynamically link modules into the compiler

Constructors

Linkable |
Fields linkableTime :: !UTCTime Time at which this linkable was built (i.e. when the bytecodes were produced, or the mod date on the files) linkableModule :: !Module The linkable module itself linkableParts :: NonEmpty LinkablePart Files and chunks of code to link.

#### Instances

Instances details

Outputable Linkable # |
Instance details Defined in GHC.Linker.Types Methods ppr :: Linkable -> SDoc #

data LinkablePart #

Objects which have yet to be linked by the compiler

Constructors

DotO |
Fields ObjFile An object file (.o) LinkableObjectSort Whether the object is an internal, intermediate build product that should not be adapted to the interpreter's way. Used for foreign stubs loaded from interfaces.
DotA FilePath | Static archive file (.a)
DotDLL FilePath | Dynamically linked library file (.so, .dll, .dylib)
CoreBindings WholeCoreBindings | Serialised core which we can turn into BCOs (or object files), or used by some other backend See Note [Interface Files with Core Definitions]
LazyBCOs |
Fields CompiledByteCode Some BCOs generated on-demand when forced. This is used for WholeCoreBindings, see Note [Interface Files with Core Definitions] [FilePath] Objects containing foreign stubs and files
BCOs CompiledByteCode | A byte-code object, lives only in memory.

#### Instances

Instances details

Outputable LinkablePart # |
Instance details Defined in GHC.Linker.Types Methods ppr :: LinkablePart -> SDoc #

data LinkableObjectSort #

Classify the provenance of `.o` products.

Constructors

ModuleObject | The object is the final product for a module. When linking splices, its file extension will be adapted to the interpreter's way if needed.
ForeignObject | The object was created from generated code for foreign stubs or foreign sources added by the user. Its file extension must be preserved, since there are no objects for alternative ways available.

linkableIsNativeCodeOnly :: Linkable -> Bool #

Return true if the linkable only consists of native code (no BCO)

linkableObjs :: Linkable -> [FilePath] #

List the native objects (.o) of a linkable

linkableLibs :: Linkable -> [LinkablePart] #

List the native libraries (.so/.dll) of a linkable

linkableFiles :: Linkable -> [FilePath] #

List the paths of the native objects and libraries (.o.so.dll)

linkableBCOs :: Linkable -> [CompiledByteCode] #

List the BCOs parts of a linkable.

This excludes the LazyBCOs and the CoreBindings parts

linkableNativeParts :: Linkable -> [LinkablePart] #

List the native linkable parts (.o.so.dll) of a linkable

linkablePartitionParts :: Linkable -> ([LinkablePart], [LinkablePart]) #

Split linkable parts into (native code parts, BCOs parts)

linkablePartPath :: LinkablePart -> Maybe FilePath #

Get the FilePath of linkable part (if applicable)

linkablePartAllBCOs :: LinkablePart -> [CompiledByteCode] #

Retrieve the compiled byte-code from the linkable part.

Contrary to linkableBCOs, this includes byte-code from LazyBCOs.

isNativeCode :: LinkablePart -> Bool #

Is the part a native object or library? (.o.so.dll)

isNativeLib :: LinkablePart -> Bool #

Is the part a native library? (.so/.dll)

linkableFilterByteCode :: Linkable -> Maybe Linkable #

Transform the `LinkablePart` list in this `Linkable` to contain only byte code without `LazyBCOs`. If no `LinkablePart` remains, return `Nothing`.

linkableFilterNative :: Linkable -> Maybe Linkable #

Transform the `LinkablePart` list in this `Linkable` to contain only object code files (.o, .a, .so) without `LazyBCOs`. If no `LinkablePart` remains, return `Nothing`.

partitionLinkables :: [Linkable] -> ([Linkable], [Linkable]) #

Split the `LinkablePart` lists in each `Linkable` into only object code files (.o, .a, .so) and only byte code, without `LazyBCOs`, and return two lists containing the nonempty `Linkable`s for each.