ghc-9.10.3: The GHC API

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

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 Source # |
Instance details Defined in GHC.StgToJS.Object Methods showsPrec :: Int -> ObjectKind -> ShowS # show :: ObjectKind -> String # showList :: [ObjectKind] -> ShowS #
Eq ObjectKind Source # |
Instance details Defined in GHC.StgToJS.Object Methods (==) :: ObjectKind -> ObjectKind -> Bool # (/=) :: ObjectKind -> ObjectKind -> Bool #
Ord ObjectKind Source # |
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) Source #

Get the kind of a file object, if any

getObjectKindBS :: ByteString -> Maybe ObjectKind Source #

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

# JS object

data JSOptions Source #

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

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

getOptionsFromJsFile Source #

Arguments

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

Parse option pragma in JS file

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

Write a JS object (embed some handwritten JS code)

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

Read a JS object from file

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

Read a JS object from BinHandle

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

Read a JS object from ByteString

# HS object

putObject Source #

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

Parse object header

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

Parse object body. Must be called after a successful getObjectHeader

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

Parse object

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

Read object from file

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

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

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

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

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

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

Reads only the part necessary to get the block info

isGlobalBlock :: BlockId -> Bool Source #

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

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

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 Source # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> IndexEntry -> IO () Source # put :: BinHandle -> IndexEntry -> IO (Bin IndexEntry) Source # get :: BinHandle -> IO IndexEntry Source #

data LocatedBlockInfo Source #

Constructors

LocatedBlockInfo |

Fields

- lbi_loc :: !BlockLocation

  Where to find the blocks

- lbi_info :: !BlockInfo

  Block information

data BlockInfo Source #

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 Source # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> BlockInfo -> IO () Source # put :: BinHandle -> BlockInfo -> IO (Bin BlockInfo) Source # get :: BinHandle -> IO BlockInfo Source #
Outputable BlockInfo Source # |
Instance details Defined in GHC.StgToJS.Object Methods ppr :: BlockInfo -> SDoc Source #

data BlockDeps Source #

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 Source # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> BlockDeps -> IO () Source # put :: BinHandle -> BlockDeps -> IO (Bin BlockDeps) Source # get :: BinHandle -> IO BlockDeps Source #

data BlockLocation Source #

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

type BlockId = Int Source #

type BlockIds = IntSet Source #

data BlockRef Source #

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 Source # |
Instance details Defined in GHC.StgToJS.Object Methods (==) :: BlockRef -> BlockRef -> Bool # (/=) :: BlockRef -> BlockRef -> Bool #
Ord BlockRef Source # |
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 Source #

Exported Functions

Constructors

ExportedFun |

Fields

- funModule :: !Module

  The module containing the function

- funSymbol :: !LexicalFastString

  The function

#### Instances

Instances details

Binary ExportedFun Source # |
Instance details Defined in GHC.StgToJS.Object Methods put_ :: BinHandle -> ExportedFun -> IO () Source # put :: BinHandle -> ExportedFun -> IO (Bin ExportedFun) Source # get :: BinHandle -> IO ExportedFun Source #
Outputable ExportedFun Source # |
Instance details Defined in GHC.StgToJS.Object Methods ppr :: ExportedFun -> SDoc Source #
Eq ExportedFun Source # |
Instance details Defined in GHC.StgToJS.Object Methods (==) :: ExportedFun -> ExportedFun -> Bool # (/=) :: ExportedFun -> ExportedFun -> Bool #
Ord ExportedFun Source # |
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 Source # |
Instance details Methods put_ :: BinHandle -> Ident -> IO () Source # put :: BinHandle -> Ident -> IO (Bin Ident) Source # get :: BinHandle -> IO Ident Source #
Binary AOp Source # |
Instance details Methods put_ :: BinHandle -> AOp -> IO () Source # put :: BinHandle -> AOp -> IO (Bin AOp) Source # get :: BinHandle -> IO AOp Source #
Binary JExpr Source # |
Instance details Methods put_ :: BinHandle -> JExpr -> IO () Source # put :: BinHandle -> JExpr -> IO (Bin JExpr) Source # get :: BinHandle -> IO JExpr Source #
Binary JStat Source # |
Instance details Methods put_ :: BinHandle -> JStat -> IO () Source # put :: BinHandle -> JStat -> IO (Bin JStat) Source # get :: BinHandle -> IO JStat Source #
Binary JVal Source # |
Instance details Methods put_ :: BinHandle -> JVal -> IO () Source # put :: BinHandle -> JVal -> IO (Bin JVal) Source # get :: BinHandle -> IO JVal Source #
Binary Op Source # |
Instance details Methods put_ :: BinHandle -> Op -> IO () Source # put :: BinHandle -> Op -> IO (Bin Op) Source # get :: BinHandle -> IO Op Source #
Binary UOp Source # |
Instance details Methods put_ :: BinHandle -> UOp -> IO () Source # put :: BinHandle -> UOp -> IO (Bin UOp) Source # get :: BinHandle -> IO UOp Source #
Binary CILayout Source # |
Instance details Methods put_ :: BinHandle -> CILayout -> IO () Source # put :: BinHandle -> CILayout -> IO (Bin CILayout) Source # get :: BinHandle -> IO CILayout Source #
Binary CIRegs Source # |
Instance details Methods put_ :: BinHandle -> CIRegs -> IO () Source # put :: BinHandle -> CIRegs -> IO (Bin CIRegs) Source # get :: BinHandle -> IO CIRegs Source #
Binary CIStatic Source # |
Instance details Methods put_ :: BinHandle -> CIStatic -> IO () Source # put :: BinHandle -> CIStatic -> IO (Bin CIStatic) Source # get :: BinHandle -> IO CIStatic Source #
Binary CIType Source # |
Instance details Methods put_ :: BinHandle -> CIType -> IO () Source # put :: BinHandle -> CIType -> IO (Bin CIType) Source # get :: BinHandle -> IO CIType Source #
Binary ClosureInfo Source # |
Instance details Methods put_ :: BinHandle -> ClosureInfo -> IO () Source # put :: BinHandle -> ClosureInfo -> IO (Bin ClosureInfo) Source # get :: BinHandle -> IO ClosureInfo Source #
Binary ExpFun Source # |
Instance details Methods put_ :: BinHandle -> ExpFun -> IO () Source # put :: BinHandle -> ExpFun -> IO (Bin ExpFun) Source # get :: BinHandle -> IO ExpFun Source #
Binary ForeignJSRef Source # |
Instance details Methods put_ :: BinHandle -> ForeignJSRef -> IO () Source # put :: BinHandle -> ForeignJSRef -> IO (Bin ForeignJSRef) Source # get :: BinHandle -> IO ForeignJSRef Source #
Binary JSFFIType Source # |
Instance details Methods put_ :: BinHandle -> JSFFIType -> IO () Source # put :: BinHandle -> JSFFIType -> IO (Bin JSFFIType) Source # get :: BinHandle -> IO JSFFIType Source #
Binary JSRep Source # |
Instance details Methods put_ :: BinHandle -> JSRep -> IO () Source # put :: BinHandle -> JSRep -> IO (Bin JSRep) Source # get :: BinHandle -> IO JSRep Source #
Binary StaticArg Source # |
Instance details Methods put_ :: BinHandle -> StaticArg -> IO () Source # put :: BinHandle -> StaticArg -> IO (Bin StaticArg) Source # get :: BinHandle -> IO StaticArg Source #
Binary StaticInfo Source # |
Instance details Methods put_ :: BinHandle -> StaticInfo -> IO () Source # put :: BinHandle -> StaticInfo -> IO (Bin StaticInfo) Source # get :: BinHandle -> IO StaticInfo Source #
Binary StaticLit Source # |
Instance details Methods put_ :: BinHandle -> StaticLit -> IO () Source # put :: BinHandle -> StaticLit -> IO (Bin StaticLit) Source # get :: BinHandle -> IO StaticLit Source #
Binary StaticUnboxed Source # |
Instance details Methods put_ :: BinHandle -> StaticUnboxed -> IO () Source # put :: BinHandle -> StaticUnboxed -> IO (Bin StaticUnboxed) Source # get :: BinHandle -> IO StaticUnboxed Source #
Binary StaticVal Source # |
Instance details Methods put_ :: BinHandle -> StaticVal -> IO () Source # put :: BinHandle -> StaticVal -> IO (Bin StaticVal) Source # get :: BinHandle -> IO StaticVal Source #