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

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file LICENSE)
Maintainer | Sylvain Henry <sylvain.henry@iohk.io> Jeffrey Young <jeffrey.young@iohk.io> Luite Stegeman <luite.stegeman@iohk.io> Josh Meredith <josh.meredith@iohk.io>
Stability | experimental Serialization/deserialization of binary .o files for the JavaScript backend
Safe Haskell | Ignore
Language | GHC2021

GHC.StgToJS.Object

Contents

- JS object
- HS object
- Orphan instances

Description

Synopsis

- data ObjectKind
  - = ObjJs
  - | ObjHs
  - | ObjCc
- getObjectKind :: FilePath -> IO (Maybe ObjectKind)
- getObjectKindBS :: ByteString -> Maybe ObjectKind
- data JSOptions = JSOptions {
  - enableCPP :: !Bool
  - emccExtraOptions :: ![String]
  - emccExportedFunctions :: ![String]
  - emccExportedRuntimeMethods :: ![String]
  }
- defaultJSOptions :: JSOptions
- getOptionsFromJsFile :: FilePath -> IO JSOptions
- writeJSObject :: JSOptions -> ByteString -> FilePath -> IO ()
- readJSObject :: FilePath -> IO (JSOptions, ByteString)
- parseJSObject :: BinHandle -> IO (JSOptions, ByteString)
- parseJSObjectBS :: ByteString -> IO (JSOptions, ByteString)
- putObject :: BinHandle -> ModuleName -> BlockInfo -> [ObjBlock] -> IO ()
- getObjectHeader :: BinHandle -> IO (Either String ModuleName)
- getObjectBody :: BinHandle -> ModuleName -> IO Object
- getObject :: BinHandle -> IO (Maybe Object)
- readObject :: FilePath -> IO (Maybe Object)
- getObjectBlocks :: Object -> BlockIds -> IO [ObjBlock]
- readObjectBlocks :: FilePath -> BlockIds -> IO [ObjBlock]
- readObjectBlockInfo :: FilePath -> IO (Maybe BlockInfo)
- isGlobalBlock :: BlockId -> Bool
- data Object = Object {
  - objModuleName :: !ModuleName
  - objHandle :: !BinHandle
  - objPayloadOffset :: !(Bin ObjBlock)
  - objBlockInfo :: !BlockInfo
  - objIndex :: !Index
  }
- data IndexEntry = IndexEntry {
  - idxSymbols :: ![FastString]
  - idxOffset :: !(Bin ObjBlock)
  }
- data LocatedBlockInfo = LocatedBlockInfo {
  - lbi_loc :: !BlockLocation
  - lbi_info :: !BlockInfo
  }
- data BlockInfo = BlockInfo {
  - bi_module :: !Module
  - bi_must_link :: !BlockIds
  - bi_exports :: !(Map ExportedFun BlockId)
  - bi_block_deps :: !(Array BlockId BlockDeps)
  }
- data BlockDeps = BlockDeps {
  - blockBlockDeps :: [BlockId]
  - blockFunDeps :: [ExportedFun]
  }
- data BlockLocation
  - = ObjectFile FilePath
  - | ArchiveFile FilePath
  - | InMemory String Object
- type BlockId = Int
- type BlockIds = IntSet
- data BlockRef = BlockRef {
  - block_ref_mod :: !Module
  - block_ref_idx :: !BlockId
  }
- data ExportedFun = ExportedFun {
  - funModule :: !Module
  - funSymbol :: !LexicalFastString
  }

# Documentation

data ObjectKind #

Different kinds of object (.o) supported by the JS backend

Constructors

ObjJs | JavaScript source embedded in a .o
ObjHs | JS backend object for Haskell code
ObjCc | Wasm module object as produced by emcc

#### Instances

Instances details

Show ObjectKind # |
Instance details Defined in GHC.StgToJS.Object Methods showsPrec :: Int -> ObjectKind -> ShowS # show :: ObjectKind -> String # showList :: [ObjectKind] -> ShowS #
Eq ObjectKind # |
Instance details Defined in GHC.StgToJS.Object Methods (==) :: ObjectKind -> ObjectKind -> Bool # (/=) :: ObjectKind -> ObjectKind -> Bool #
Ord ObjectKind # |
Instance details Defined in GHC.StgToJS.Object Methods compare :: ObjectKind -> ObjectKind -> Ordering # (<) :: ObjectKind -> ObjectKind -> Bool # (<=) :: ObjectKind -> ObjectKind -> Bool # (>) :: ObjectKind -> ObjectKind -> Bool # (>=) :: ObjectKind -> ObjectKind -> Bool # max :: ObjectKind -> ObjectKind -> ObjectKind # min :: ObjectKind -> ObjectKind -> ObjectKind #

getObjectKind :: FilePath -> IO (Maybe ObjectKind) #

Get the kind of a file object, if any

getObjectKindBS :: ByteString -> Maybe ObjectKind #

Get the kind of an object stored in a bytestring, if any

# JS object

data JSOptions #

Options obtained from pragmas in JS files

Constructors

JSOptions |

Fields

- enableCPP :: !Bool

  Enable CPP on the JS file

- emccExtraOptions :: ![String]

  Pass additional options to emcc at link time

- emccExportedFunctions :: ![String]

  Arguments for `-sEXPORTED_FUNCTIONS`

- emccExportedRuntimeMethods :: ![String]

  Arguments for `-sEXPORTED_RUNTIME_METHODS`

#### Instances

Instances details

Semigroup JSOptions # |
Instance details Defined in GHC.StgToJS.Object Methods (<>) :: JSOptions -> JSOptions -> JSOptions # sconcat :: NonEmpty JSOptions -> JSOptions # stimes :: Integral b => b -> JSOptions -> JSOptions #
Binary JSOptions # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> JSOptions -> IO () # put :: BinHandle -> JSOptions -> IO (Bin JSOptions) # get :: BinHandle -> IO JSOptions #
Eq JSOptions # |
Instance details Defined in GHC.StgToJS.Object Methods (==) :: JSOptions -> JSOptions -> Bool # (/=) :: JSOptions -> JSOptions -> Bool #
Ord JSOptions # |
Instance details Defined in GHC.StgToJS.Object Methods compare :: JSOptions -> JSOptions -> Ordering # (<) :: JSOptions -> JSOptions -> Bool # (<=) :: JSOptions -> JSOptions -> Bool # (>) :: JSOptions -> JSOptions -> Bool # (>=) :: JSOptions -> JSOptions -> Bool # max :: JSOptions -> JSOptions -> JSOptions # min :: JSOptions -> JSOptions -> JSOptions #

defaultJSOptions :: JSOptions #

getOptionsFromJsFile #

Arguments

:: FilePath | Input file
-> IO JSOptions | Parsed options.

Parse option pragma in JS file

writeJSObject :: JSOptions -> ByteString -> FilePath -> IO () #

Write a JS object (embed some handwritten JS code)

readJSObject :: FilePath -> IO (JSOptions, ByteString) #

Read a JS object from file

parseJSObject :: BinHandle -> IO (JSOptions, ByteString) #

Read a JS object from BinHandle

parseJSObjectBS :: ByteString -> IO (JSOptions, ByteString) #

Read a JS object from ByteString

# HS object

putObject #

Arguments

:: BinHandle |
-> ModuleName | module
-> BlockInfo | block infos
-> [ObjBlock] | linkable units and their symbols
-> IO () |

Given a handle to a Binary payload, add the module, `mod_name`, its dependencies, `deps`, and its linkable units to the payload.

getObjectHeader :: BinHandle -> IO (Either String ModuleName) #

Parse object header

getObjectBody :: BinHandle -> ModuleName -> IO Object #

Parse object body. Must be called after a successful getObjectHeader

getObject :: BinHandle -> IO (Maybe Object) #

Parse object

readObject :: FilePath -> IO (Maybe Object) #

Read object from file

The object is still in memory after this (see objHandle).

getObjectBlocks :: Object -> BlockIds -> IO [ObjBlock] #

Get blocks in the object file, using the given filtering function

readObjectBlocks :: FilePath -> BlockIds -> IO [ObjBlock] #

Read blocks in the object file, using the given filtering function

readObjectBlockInfo :: FilePath -> IO (Maybe BlockInfo) #

Reads only the part necessary to get the block info

isGlobalBlock :: BlockId -> Bool #

we use the convention that the first block (0) is a module-global block that's always included when something from the module is loaded. everything in a module implicitly depends on the global block. The global block itself can't have dependencies

data Object #

A HS object file

Constructors

Object |

Fields

- objModuleName :: !ModuleName

  name of the module

- objHandle :: !BinHandle

  BinHandle that can be used to read the ObjBlocks

- objPayloadOffset :: !(Bin ObjBlock)

  Offset of the payload (units)

- objBlockInfo :: !BlockInfo

  Information about blocks

- objIndex :: !Index

  Block index: symbols per block and block offset in the object file

data IndexEntry #

Constructors

IndexEntry |

Fields

- idxSymbols :: ![FastString]

  Symbols exported by a block

- idxOffset :: !(Bin ObjBlock)

  Offset of the block in the object file

#### Instances

Instances details

Binary IndexEntry # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> IndexEntry -> IO () # put :: BinHandle -> IndexEntry -> IO (Bin IndexEntry) # get :: BinHandle -> IO IndexEntry #

data LocatedBlockInfo #

Constructors

LocatedBlockInfo |

Fields

- lbi_loc :: !BlockLocation

  Where to find the blocks

- lbi_info :: !BlockInfo

  Block information

data BlockInfo #

Information about blocks (linkable units)

Constructors

BlockInfo |

Fields

- bi_module :: !Module

  Module they were generated from

- bi_must_link :: !BlockIds

  blocks that always need to be linked when this object is loaded (e.g. everything that contains initializer code or foreign exports)

- bi_exports :: !(Map ExportedFun BlockId)

  exported Haskell functions -> block

- bi_block_deps :: !(Array BlockId BlockDeps)

  dependencies of each block

#### Instances

Instances details

Binary BlockInfo # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> BlockInfo -> IO () # put :: BinHandle -> BlockInfo -> IO (Bin BlockInfo) # get :: BinHandle -> IO BlockInfo #
Outputable BlockInfo # |
Instance details Defined in GHC.StgToJS.Object Methods ppr :: BlockInfo -> SDoc #

data BlockDeps #

Constructors

BlockDeps |

Fields

- blockBlockDeps :: [BlockId]

  dependencies on blocks in this object

- blockFunDeps :: [ExportedFun]

  dependencies on exported symbols in other objects , blockForeignExported :: [ExpFun] , blockForeignImported :: [ForeignRef]

#### Instances

Instances details

Binary BlockDeps # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> BlockDeps -> IO () # put :: BinHandle -> BlockDeps -> IO (Bin BlockDeps) # get :: BinHandle -> IO BlockDeps #

data BlockLocation #

Where are the blocks

Constructors

ObjectFile FilePath | In an object file at path
ArchiveFile FilePath | In a Ar file at path
InMemory String Object | In memory

#### Instances

Instances details

Outputable BlockLocation # |
Instance details Defined in GHC.StgToJS.Object Methods ppr :: BlockLocation -> SDoc #

type BlockId = Int #

type BlockIds = IntSet #

data BlockRef #

A `BlockRef` is a pair of a module and the index of the block in the object file

Constructors

BlockRef |

Fields

- block_ref_mod :: !Module

  Module

- block_ref_idx :: !BlockId

  Block index in the object file

#### Instances

Instances details

Eq BlockRef # |
Instance details Defined in GHC.StgToJS.Object Methods (==) :: BlockRef -> BlockRef -> Bool # (/=) :: BlockRef -> BlockRef -> Bool #
Ord BlockRef # |
Instance details Defined in GHC.StgToJS.Object Methods compare :: BlockRef -> BlockRef -> Ordering # (<) :: BlockRef -> BlockRef -> Bool # (<=) :: BlockRef -> BlockRef -> Bool # (>) :: BlockRef -> BlockRef -> Bool # (>=) :: BlockRef -> BlockRef -> Bool # max :: BlockRef -> BlockRef -> BlockRef # min :: BlockRef -> BlockRef -> BlockRef #

data ExportedFun #

Exported Functions

Constructors

ExportedFun |

Fields

- funModule :: !Module

  The module containing the function

- funSymbol :: !LexicalFastString

  The function

#### Instances

Instances details

Binary ExportedFun # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> ExportedFun -> IO () # put :: BinHandle -> ExportedFun -> IO (Bin ExportedFun) # get :: BinHandle -> IO ExportedFun #
Outputable ExportedFun # |
Instance details Defined in GHC.StgToJS.Object Methods ppr :: ExportedFun -> SDoc #
Eq ExportedFun # |
Instance details Defined in GHC.StgToJS.Object Methods (==) :: ExportedFun -> ExportedFun -> Bool # (/=) :: ExportedFun -> ExportedFun -> Bool #
Ord ExportedFun # |
Instance details Defined in GHC.StgToJS.Object Methods compare :: ExportedFun -> ExportedFun -> Ordering # (<) :: ExportedFun -> ExportedFun -> Bool # (<=) :: ExportedFun -> ExportedFun -> Bool # (>) :: ExportedFun -> ExportedFun -> Bool # (>=) :: ExportedFun -> ExportedFun -> Bool # max :: ExportedFun -> ExportedFun -> ExportedFun # min :: ExportedFun -> ExportedFun -> ExportedFun #

# Orphan instances

Binary Ident # |
Instance details Methods put_ :: BinHandle -> Ident -> IO () # put :: BinHandle -> Ident -> IO (Bin Ident) # get :: BinHandle -> IO Ident #
Binary AOp # |
Instance details Methods put_ :: BinHandle -> AOp -> IO () # put :: BinHandle -> AOp -> IO (Bin AOp) # get :: BinHandle -> IO AOp #
Binary JExpr # |
Instance details Methods put_ :: BinHandle -> JExpr -> IO () # put :: BinHandle -> JExpr -> IO (Bin JExpr) # get :: BinHandle -> IO JExpr #
Binary JStat # |
Instance details Methods put_ :: BinHandle -> JStat -> IO () # put :: BinHandle -> JStat -> IO (Bin JStat) # get :: BinHandle -> IO JStat #
Binary JVal # |
Instance details Methods put_ :: BinHandle -> JVal -> IO () # put :: BinHandle -> JVal -> IO (Bin JVal) # get :: BinHandle -> IO JVal #
Binary Op # |
Instance details Methods put_ :: BinHandle -> Op -> IO () # put :: BinHandle -> Op -> IO (Bin Op) # get :: BinHandle -> IO Op #
Binary UOp # |
Instance details Methods put_ :: BinHandle -> UOp -> IO () # put :: BinHandle -> UOp -> IO (Bin UOp) # get :: BinHandle -> IO UOp #
Binary CILayout # |
Instance details Methods put_ :: BinHandle -> CILayout -> IO () # put :: BinHandle -> CILayout -> IO (Bin CILayout) # get :: BinHandle -> IO CILayout #
Binary CIRegs # |
Instance details Methods put_ :: BinHandle -> CIRegs -> IO () # put :: BinHandle -> CIRegs -> IO (Bin CIRegs) # get :: BinHandle -> IO CIRegs #
Binary CIStatic # |
Instance details Methods put_ :: BinHandle -> CIStatic -> IO () # put :: BinHandle -> CIStatic -> IO (Bin CIStatic) # get :: BinHandle -> IO CIStatic #
Binary CIType # |
Instance details Methods put_ :: BinHandle -> CIType -> IO () # put :: BinHandle -> CIType -> IO (Bin CIType) # get :: BinHandle -> IO CIType #
Binary ClosureInfo # |
Instance details Methods put_ :: BinHandle -> ClosureInfo -> IO () # put :: BinHandle -> ClosureInfo -> IO (Bin ClosureInfo) # get :: BinHandle -> IO ClosureInfo #
Binary ExpFun # |
Instance details Methods put_ :: BinHandle -> ExpFun -> IO () # put :: BinHandle -> ExpFun -> IO (Bin ExpFun) # get :: BinHandle -> IO ExpFun #
Binary ForeignJSRef # |
Instance details Methods put_ :: BinHandle -> ForeignJSRef -> IO () # put :: BinHandle -> ForeignJSRef -> IO (Bin ForeignJSRef) # get :: BinHandle -> IO ForeignJSRef #
Binary JSFFIType # |
Instance details Methods put_ :: BinHandle -> JSFFIType -> IO () # put :: BinHandle -> JSFFIType -> IO (Bin JSFFIType) # get :: BinHandle -> IO JSFFIType #
Binary JSRep # |
Instance details Methods put_ :: BinHandle -> JSRep -> IO () # put :: BinHandle -> JSRep -> IO (Bin JSRep) # get :: BinHandle -> IO JSRep #
Binary StaticArg # |
Instance details Methods put_ :: BinHandle -> StaticArg -> IO () # put :: BinHandle -> StaticArg -> IO (Bin StaticArg) # get :: BinHandle -> IO StaticArg #
Binary StaticInfo # |
Instance details Methods put_ :: BinHandle -> StaticInfo -> IO () # put :: BinHandle -> StaticInfo -> IO (Bin StaticInfo) # get :: BinHandle -> IO StaticInfo #
Binary StaticLit # |
Instance details Methods put_ :: BinHandle -> StaticLit -> IO () # put :: BinHandle -> StaticLit -> IO (Bin StaticLit) # get :: BinHandle -> IO StaticLit #
Binary StaticUnboxed # |
Instance details Methods put_ :: BinHandle -> StaticUnboxed -> IO () # put :: BinHandle -> StaticUnboxed -> IO (Bin StaticUnboxed) # get :: BinHandle -> IO StaticUnboxed #
Binary StaticVal # |
Instance details Methods put_ :: BinHandle -> StaticVal -> IO () # put :: BinHandle -> StaticVal -> IO (Bin StaticVal) # get :: BinHandle -> IO StaticVal #