ghc-lib-parser-9.12.2.20250421: 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)]
  }
- 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
- 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 Source #

Constructors

Loader |

Fields

- loader_state :: MVar (Maybe LoaderState)

data LoaderState Source #

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)

uninitializedLoader :: IO Loader Source #

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

data LinkerEnv Source #

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 Source #

type ClosureEnv = NameEnv (Name, ForeignHValue) Source #

emptyClosureEnv :: ClosureEnv Source #

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

type LinkableSet = ModuleEnv Linkable Source #

mkLinkableSet :: [Linkable] -> LinkableSet Source #

unionLinkableSet :: LinkableSet -> LinkableSet -> LinkableSet Source #

Union of LinkableSets.

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

type ObjFile = FilePath Source #

data SptEntry Source #

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 Source # |
Instance details Defined in GHC.Types.SptEntry Methods ppr :: SptEntry -> SDoc Source #

data LibrarySpec Source #

Constructors

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

#### Instances

Instances details

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

data LoadedPkgInfo Source #

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 Source # |
Instance details Defined in GHC.Linker.Types Methods ppr :: LoadedPkgInfo -> SDoc Source #

type PkgsLoaded = UniqDFM UnitId LoadedPkgInfo Source #

# Linkable

data Linkable Source #

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 Source # |
Instance details Defined in GHC.Linker.Types Methods ppr :: Linkable -> SDoc Source #

data LinkablePart Source #

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 Source # |
Instance details Defined in GHC.Linker.Types Methods ppr :: LinkablePart -> SDoc Source #

data LinkableObjectSort Source #

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 Source #

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

linkableObjs :: Linkable -> [FilePath] Source #

List the native objects (.o) of a linkable

linkableLibs :: Linkable -> [LinkablePart] Source #

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

linkableFiles :: Linkable -> [FilePath] Source #

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

linkableBCOs :: Linkable -> [CompiledByteCode] Source #

List the BCOs parts of a linkable.

This excludes the LazyBCOs and the CoreBindings parts

linkableNativeParts :: Linkable -> [LinkablePart] Source #

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

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

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

linkablePartPath :: LinkablePart -> Maybe FilePath Source #

Get the FilePath of linkable part (if applicable)

linkablePartAllBCOs :: LinkablePart -> [CompiledByteCode] Source #

Retrieve the compiled byte-code from the linkable part.

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

isNativeCode :: LinkablePart -> Bool Source #

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

isNativeLib :: LinkablePart -> Bool Source #

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

linkableFilterByteCode :: Linkable -> Maybe Linkable Source #

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

linkableFilterNative :: Linkable -> Maybe Linkable Source #

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]) Source #

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.