Wolfgang Jeltsch pushed to branch wip/jeltsch/textual-bytecode-output at Glasgow Haskell Compiler / GHC Commits: 36332be8 by Wolfgang Jeltsch at 2026-07-17T17:21:16+03:00 Remove the now unneeded enabling of scoped type variables - - - - - 54b4b8a1 by Wolfgang Jeltsch at 2026-07-17T18:14:49+03:00 Fix a documentation linking error - - - - - 8a39d728 by Wolfgang Jeltsch at 2026-07-17T18:42:06+03:00 Assert that `pprFixedSizeNatural` takes a natural number - - - - - 7db7343b by Wolfgang Jeltsch at 2026-07-17T20:27:36+03:00 Fix Markup in a comment - - - - - 2f58c3a2 by Wolfgang Jeltsch at 2026-07-17T20:37:20+03:00 Add Haddock documentation - - - - - 1 changed file: - compiler/GHC/ByteCode/Show.hs Changes: ===================================== compiler/GHC/ByteCode/Show.hs ===================================== @@ -1,8 +1,8 @@ {-# LANGUAGE ImportQualifiedPost #-} {-# LANGUAGE RecordWildCards #-} -{-# LANGUAGE ScopedTypeVariables #-} --- | […] +-- | This module implements the output of textual information about the contents +-- of bytecode files. It is the backbone of the @--show-byte-code@ option. module GHC.ByteCode.Show (showByteCode) where import Prelude ((+), (-), Integral, div) @@ -79,7 +79,7 @@ import GHC.Driver.Env.Types (HscEnv) import GHCi.FFI (FFIType) import GHCi.Message (ConInfoTable (..)) --- | […] +-- | Outputs textual information about the contents of a bytecode file. showByteCode :: Logger -> HscEnv -> FilePath -> IO () showByteCode logger env path = do byteCode <- readOnDiskModuleByteCode env path @@ -88,7 +88,7 @@ showByteCode logger env path = do noSrcSpan (withPprStyle defaultDumpStyle $ pprOnDiskModuleByteCode byteCode) --- | […] +-- | Constructs textual information about the contents of a bytecode file. pprOnDiskModuleByteCode :: OnDiskModuleByteCode -> SDoc pprOnDiskModuleByteCode OnDiskModuleByteCode {..} = vcat [ @@ -97,15 +97,15 @@ pprOnDiskModuleByteCode OnDiskModuleByteCode {..} pprCompiledByteCode odgbc_module $ odgbc_compiled_byte_code ] --- | […] +-- | Constructs textual information about the name of a module. pprModuleIdent :: Module -> SDoc pprModuleIdent = entry (text "name") . ppr --- | […] +-- | Constructs textual information about the hash of a module. pprOnDiskModuleByteCodeHash :: Fingerprint -> SDoc pprOnDiskModuleByteCodeHash = entry (text "hash") . ppr --- | […] +-- | Constructs textual information about bytecode. pprCompiledByteCode :: Module -> CompiledByteCode -> SDoc pprCompiledByteCode currentModule CompiledByteCode {..} = vcat [ @@ -117,14 +117,14 @@ pprCompiledByteCode currentModule CompiledByteCode {..} pprHPCInfo $ bc_hpc_info ] --- | […] +-- | Constructs textual information about bytecode objects. pprByteCodeObjects :: Module -> FlatBag UnlinkedBCO -> SDoc pprByteCodeObjects currentModule = entry (text "objects") . vcatOrNone . map (pprByteCodeObject currentModule) . elemsFlatBag --- | […] +-- | Constructs textual information about a single bytecode object. pprByteCodeObject :: Module -> UnlinkedBCO -> SDoc pprByteCodeObject currentModule byteCodeObject = case byteCodeObject of UnlinkedBCO {..} @@ -147,26 +147,29 @@ pprByteCodeObject currentModule byteCodeObject = case byteCodeObject of pprPointers currentModule $ unlinkedStaticConPtrs ] --- | […] +-- | Constructs textual information about the arity of an ordinary bytecode +-- object. pprArity :: Int -> SDoc pprArity = entry (text "arity") . ppr --- | […] +-- | Constructs textual information about the data constructor name of a +-- static-construction bytecode object. pprDataConstructorName :: Name -> SDoc pprDataConstructorName = entry (text "data constructor name") . ppr --- | […] +-- | Constructs textual information about the liftedness of a +-- static-construction bytecode object. pprLiftedness :: Bool -> SDoc pprLiftedness = entry (text "lifted") . noOrYes --- | […] +-- | Constructs textual information about literals. pprLiterals :: Module -> FlatBag BCONPtr -> SDoc pprLiterals currentModule = entry (text "literals") . vcatOrNone . map (pprLiteral currentModule) . elemsFlatBag --- | […] +-- | Constructs textual information about a single literal. pprLiteral :: Module -> BCONPtr -> SDoc pprLiteral currentModule literal = case literal of BCONPtrWord word @@ -194,20 +197,20 @@ pprLiteral currentModule literal = case literal of -> text "cost center of breakpoint" <+> pprInternalBreakpointID currentModule breakpointID --- | […] +-- | Constructs textual information about some FFI info. pprFFIInfo :: FFIInfo -> SDoc pprFFIInfo FFIInfo {..} = hsep (map (pprFFIType >>> (<+> text "->")) ffiInfoArgs) <+> pprFFIType ffiInfoRet --- | […] +-- | Constructs textual information about an FFI type. pprFFIType :: FFIType -> SDoc pprFFIType ffiType = assert (take 3 ident == "FFI") $ text (drop 3 ident) where ident :: String ident = show ffiType --- | […] +-- | Constructs textual information about the ID of a bytecode breakpoint. pprInternalBreakpointID :: Module -> InternalBreakpointId -> SDoc pprInternalBreakpointID currentModule InternalBreakpointId {..} | ibi_info_mod == currentModule = indexDoc @@ -219,14 +222,14 @@ pprInternalBreakpointID currentModule InternalBreakpointId {..} indexDoc :: SDoc indexDoc = ppr ibi_info_index --- | […] +-- | Constructs textual information about pointers. pprPointers :: Module -> FlatBag BCOPtr -> SDoc pprPointers currentModule = entry (text "utilized items") . vcatOrNone . map (pprPointer currentModule) . elemsFlatBag --- | […] +-- | Constructs textual information about a single pointer. pprPointer :: Module -> BCOPtr -> SDoc pprPointer currentModule pointer = case pointer of BCOPtrName name @@ -238,13 +241,13 @@ pprPointer currentModule pointer = case pointer of BCOPtrBreakArray breakArrayModule -> text "break array of module" <+> quotes (ppr breakArrayModule) --- | […] +-- | Constructs textual information about data constructor info tables. pprDataConstructorInfoTables :: [(Name, ConInfoTable)] -> SDoc pprDataConstructorInfoTables = entry (text "data constructor info tables") . vcatOrNone . map (uncurry pprDataConstructorInfoTable) --- | […] +-- | Constructs textual information about a single data constructor info table. pprDataConstructorInfoTable :: Name -> ConInfoTable -> SDoc pprDataConstructorInfoTable dataConstrName ConInfoTable {..} = entry (text "info table of" <+> quotes (ppr dataConstrName)) $ @@ -253,21 +256,21 @@ pprDataConstructorInfoTable dataConstrName ConInfoTable {..} pprNonPointerWordCount $ conItblNPtrs ] --- | […] +-- | Constructs textual information about a number of pointer words. pprPointerWordCount :: Int -> SDoc pprPointerWordCount = entry (text "number of words for pointers") . ppr --- | […] +-- | Constructs textual information about a number of non-pointer words. pprNonPointerWordCount :: Int -> SDoc pprNonPointerWordCount = entry (text "number of words for non-pointers") . ppr --- | […] +-- | Constructs textual information about top-level strings. pprTopLevelStrings :: [(Name, ByteString)] -> SDoc pprTopLevelStrings = entry (text "top-level strings") . vcatOrNone . map (uncurry pprTopLevelString) --- | […] +-- | Constructs textual information about a single top-level string. pprTopLevelString :: Name -> ByteString -> SDoc pprTopLevelString stringName encodedString = entry (ppr stringName) $ text $ @@ -275,13 +278,13 @@ pprTopLevelString stringName encodedString = entry (ppr stringName) $ utf8DecodeByteString $ encodedString --- | […] +-- | Constructs textual information about breakpoints. pprBreakpoints :: Module -> Maybe InternalModBreaks -> SDoc pprBreakpoints currentModule = entry (text "breakpoints") . maybe (text "<none>") (pprBreakpointsData currentModule) --- | […] +-- | Constructs textual information about a single breakpoint. pprBreakpointsData :: Module -> InternalModBreaks -> SDoc pprBreakpointsData currentModule InternalModBreaks {..} = vcat [ @@ -289,7 +292,7 @@ pprBreakpointsData currentModule InternalModBreaks {..} pprByteCodeBreakpoints currentModule $ imodBreaks_breakInfo ] --- | […] +-- | Constructs textual information about source breakpoints. pprSourceBreakpoints :: Module -> ModBreaks -> SDoc pprSourceBreakpoints currentModule ModBreaks {..} = entry (text "source breakpoints") $ @@ -301,12 +304,12 @@ pprSourceBreakpoints currentModule ModBreaks {..} (elems modBreaks_locs_) (elems modBreaks_decls) (elems modBreaks_vars) - -- The cost center infos in `modBreaks_ccs`, when present, just contain - -- textual representations of the declaration paths in `modBreaks_decls` - -- and the source spans in `modBreaks_locs_` and are therefore never + -- The cost center infos in 'modBreaks_ccs', when present, just contain + -- textual representations of the declaration paths in 'modBreaks_decls' + -- and the source spans in 'modBreaks_locs_' and are therefore never -- shown. --- | […] +-- | Constructs textual information about a single source breakpoint. pprSourceBreakpoint :: BreakTickIndex -> BinSrcSpan -> [String] @@ -320,19 +323,19 @@ pprSourceBreakpoint ix srcSpan declarationPath freeVars pprFreeVariables $ freeVars ] --- | […] +-- | Constructs textual information about a source span. pprSrcSpan :: BinSrcSpan -> SDoc pprSrcSpan = entry (text "source span") . ppr . unBinSrcSpan --- | […] +-- | Constructs textual information about a declaration path. pprDeclarationPath :: [String] -> SDoc pprDeclarationPath = entry (text "declaration path") . vcatOrEmpty . map text --- | […] +-- | Constructs textual information about free variables. pprFreeVariables :: [OccName] -> SDoc pprFreeVariables = entry (text "free variables") . vcatOrNone . map ppr --- | […] +-- | Constructs textual information about bytecode breakpoints. pprByteCodeBreakpoints :: Module -> IntMap CgBreakInfo -> SDoc pprByteCodeBreakpoints currentModule = entry (text "bytecode breakpoints") . @@ -340,7 +343,7 @@ pprByteCodeBreakpoints currentModule map (uncurry (pprByteCodeBreakpoint currentModule)) . IntMap.toList --- | […] +-- | Constructs textual information about a single bytecode breakpoint. pprByteCodeBreakpoint :: Module -> Int -> CgBreakInfo -> SDoc pprByteCodeBreakpoint currentModule ix CgBreakInfo {..} = entry (text "bytecode breakpoint" <+> ppr ix) $ @@ -353,38 +356,41 @@ pprByteCodeBreakpoint currentModule ix CgBreakInfo {..} -- That the 'cgb_resty' field holds the type of the breakpoint is apparent -- from the fact that this field is set by -- 'GHC.StgToByteCode.dehydrateCgBreakInfo' using one of its arguments and - -- 'dehydrateCgBreakInfo' is always invoked with this argument set to the - -- extension field of 'Breakpoint', which in turn holds the type of the - -- breakpoint according to Note [Tickish passes] and the comment on the - -- instance declaration of @XBreakpoint 'TickishPassStg@. + -- 'GHC.StgToByteCode.dehydrateCgBreakInfo' is always invoked with this + -- argument set to the extension field of 'Breakpoint', which in turn holds + -- the type of the breakpoint according to Note [Tickish passes] and the + -- comment on the instance declaration of @XBreakpoint 'TickishPassStg@. +-- | Constructs textual information about a type. pprType :: IfaceType -> SDoc pprType = entry (text "type") . ppr --- | […] +-- | Constructs textual information about type variables. pprTypeVariables :: [IfaceTvBndr] -> SDoc pprTypeVariables = entry (text "type variables") . vcatOrNone . map pprTypeVariableBinder --- | […] +-- | Constructs textual information about a type variable binder. pprTypeVariableBinder :: IfaceTvBndr -> SDoc pprTypeVariableBinder (name, kind) = ppr name <+> text "::" <+> ppr kind --- | […] +-- | Constructs textual information about variables. pprVariables :: [Maybe (IfaceIdBndr, Word)] -> SDoc pprVariables = entry (text "variables") . vcatOrNone . map pprVariable --- | […] +-- | Constructs textual information about a single variable. pprVariable :: Maybe (IfaceIdBndr, Word) -> SDoc pprVariable = maybe (text "<unknown>") (pprVariableBinder . fst) --- | […] +-- | Constructs textual information about a variable binder. pprVariableBinder :: IfaceIdBndr -> SDoc pprVariableBinder (multiplicity, name, type_) = text "%" <> ppr multiplicity <+> ppr name <+> text "::" <+> ppr type_ +-- | Constructs textual information about a source breakpoint corresponding to a +-- bytecode breakpoint. pprCorrespondingSourceBreakpoint :: Module -> Either InternalBreakLoc BreakpointId -> SDoc @@ -393,7 +399,7 @@ pprCorrespondingSourceBreakpoint currentModule pprBreakpointID currentModule . either internalBreakLoc id --- | […] [analogous to 'pprInternalBreakpointID' but the meaning of the index is different] +-- | Constructs textual information about the ID of a source breakpoint. pprBreakpointID :: Module -> BreakpointId -> SDoc pprBreakpointID currentModule BreakpointId {..} | bi_tick_mod == currentModule = indexDoc @@ -405,23 +411,23 @@ pprBreakpointID currentModule BreakpointId {..} indexDoc :: SDoc indexDoc = ppr bi_tick_index --- | […] +-- | Constructs textual information about static-pointer table entries. pprStaticPointerTableEntries :: [SptEntry] -> SDoc pprStaticPointerTableEntries = entry (text "static-pointer table entries") . vcatOrNone . map pprStaticPointerTableEntry --- | […] +-- | Constructs textual information about a single static-pointer table entry. pprStaticPointerTableEntry :: SptEntry -> SDoc pprStaticPointerTableEntry (SptEntry name fingerprint) = ppr fingerprint <> text ":" <+> ppr name --- | […] +-- | Constructs textual information about some HPC info. pprHPCInfo :: Strict.Maybe ByteCodeHpcInfo -> SDoc pprHPCInfo = entry (text "HPC information") . Strict.maybe (text "<none>") pprHPCInfoData --- | […] +-- | Constructs textual information about data that makes up some HPC info. pprHPCInfoData :: ByteCodeHpcInfo -> SDoc pprHPCInfoData ByteCodeHpcInfo {..} = vcat [ @@ -432,30 +438,33 @@ pprHPCInfoData ByteCodeHpcInfo {..} ] where --- | […] +-- | Constructs textual information about the hash of some HPC info. pprHPCInfoHash :: Int -> SDoc pprHPCInfoHash = entry (text "hash") . pprFixedSizeNatural --- | […] +-- | Constructs textual information about a module name. pprModuleName :: ShortByteString -> SDoc pprModuleName = entry (text "module name") . text . utf8DecodeShortByteString --- | […] +-- | Constructs textual information about a tick box name. pprTickBoxName :: ShortByteString -> SDoc pprTickBoxName = entry (text "tick box name") . text . utf8DecodeShortByteString --- | […] +-- | Constructs textual information about a number of tick counts. pprTickCount :: Int -> SDoc pprTickCount = entry (text "number of ticks") . ppr --- | […] +-- | Constructs a hexadecimal representation of a natural number such that the +-- number of hexadecimal digits fits the number of bits used to represent the +-- natural number. pprFixedSizeNatural :: (Integral a, FiniteBits a) => a -> SDoc pprFixedSizeNatural num - = text $ replicate (digitCount - length unpadded) '0' ++ unpadded + = assert (num >= 0) $ + text $ replicate (digitCount - length unpadded) '0' ++ unpadded where digitCount :: Int @@ -464,20 +473,25 @@ pprFixedSizeNatural num unpadded :: String unpadded = showHex num "" --- | […] +-- | Constructs a textual representation of a boolean, interpreting 'True' and +-- 'False' as “yes” and “no”, respectively. noOrYes :: Bool -> SDoc noOrYes bool = text (if bool then "yes" else "no") --- | […] -entry :: SDoc -> SDoc -> SDoc +-- | Constructs an entry in a list of textual data representations. +entry :: SDoc -- ^ The title of the entry + -> SDoc -- ^ The contents of the entry + -> SDoc -- ^ The entry entry title content = hang (title <> text ":") 2 content --- | […] +-- | Composes documents vertically in general, but presents an empty document +-- list as `<none`>. vcatOrNone :: [SDoc] -> SDoc vcatOrNone [] = text "<none>" vcatOrNone docs = vcat docs --- | […] +-- | Composes documents vertically in general, but presents an empty document +-- list as `<empty`>. vcatOrEmpty :: [SDoc] -> SDoc vcatOrEmpty [] = text "<empty>" vcatOrEmpty docs = vcat docs View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/aeddc354c6672f1d89903200aac7932... -- View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/compare/aeddc354c6672f1d89903200aac7932... You're receiving this email because of your account on gitlab.haskell.org. Manage all notifications: https://gitlab.haskell.org/-/profile/notifications | Help: https://gitlab.haskell.org/help