Moduleghc-lib-parser-9.14.1.20251220GHC2021

GHC.Utils.Logger

Logger

The Logger is an configurable entity that is used by the compiler to output messages on the console (stdout, stderr) and in dump files.

The behaviour of default Logger returned by initLogger can be modified with hooks. The compiler itself uses hooks in multithreaded code (--make) and it is also probably used by ghc-api users (IDEs, etc.).

In addition to hooks, the Logger supports LogFlags: basically a subset of the command-line flags that control the logger behaviour at a higher level than hooks.

Hooks are used to define how to generate a infowarningerror/dump messages
LogFlags are used to decide when and how to generate messages

7 types
2 classes
39 values

Packageghc-lib-parser-9.14.1.20251220
Exports48
LanguageGHC2021
LicenceBSD-3-Clause
SourceLogger.hs

datadata Logger

classclass HasLogger (m :: Type -> Type) where

Methods

getLogger :: m Logger

Instances6HasLogger

HasLogger CoreMDefined in ghc-lib-parser-9.14.1.20251220 · GHC.Core.Opt.Monad
HasLogger SimplMDefined in ghc-lib-parser-9.14.1.20251220 · GHC.Core.Opt.Simplify.Monad
HasLogger HscDefined in ghc-lib-parser-9.14.1.20251220 · GHC.Driver.Env.Types
HasLogger GhcDefined in ghc-lib-parser-9.14.1.20251220 · GHC.Driver.Monad
MonadIO m => HasLogger (GhcT m)Defined in ghc-lib-parser-9.14.1.20251220 · GHC.Driver.Monad
ContainsLogger env => HasLogger (IOEnv env)Defined in ghc-lib-parser-9.14.1.20251220 · GHC.Data.IOEnv

classclass ContainsLogger t where

Methods

extractLogger :: t -> Logger

Instances1ContainsLogger

ContainsLogger (Env gbl lcl)Defined in ghc-lib-parser-9.14.1.20251220 · GHC.Tc.Types

Logger setup

6 declarations

valueinitLogger :: IO Logger

typetype LogAction = LogFlags -> MessageClass -> SrcSpan -> SDoc -> IO ()

typetype LogJsonAction = LogFlags -> MessageClass -> JsonDoc -> IO ()

typetype DumpAction = LogFlags -> PprStyle -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()

typetype TraceAction a = LogFlags -> String -> SDoc -> a -> a

datadata DumpFormat

Format of a dump

Dump formats are loosely defined: dumps may contain various additional headers and annotations and they may be partial. DumpFormat is mainly a hint (e.g. for syntax highlighters).

Constructors

FormatHaskell
Haskell
FormatCore
Core
FormatSTG
STG
FormatByteCode
ByteCode
FormatCMM
Cmm
FormatASM
Assembly code
FormatC
C code/header
FormatLLVM
LLVM bytecode
FormatJS
JavaScript code
FormatText
Unstructured dump

Instances2Eq, Show

Eq DumpFormatDefined in ghc-lib-parser-9.14.1.20251220 · GHC.Utils.Logger
Show DumpFormatDefined in ghc-lib-parser-9.14.1.20251220 · GHC.Utils.Logger

Hooks

valuepopLogHook :: Logger -> Logger

Pop a log hook

valuepushLogHook :: (LogAction -> LogAction) -> Logger -> Logger

Push a log hook

valuepopJsonLogHook :: Logger -> Logger

valuepushJsonLogHook :: (LogJsonAction -> LogJsonAction) -> Logger -> Logger

Push a json log hook

valuepopDumpHook :: Logger -> Logger

Pop a dump hook

valuepushDumpHook :: (DumpAction -> DumpAction) -> Logger -> Logger

Push a dump hook

valuepopTraceHook :: Logger -> Logger

Pop a trace hook

valuepushTraceHook

:: forall a. TraceAction a -> TraceAction a
-> Logger
-> Logger

Push a trace hook

valuemakeThreadSafe :: Logger -> IO Logger

Make the logger thread-safe

Flags

datadata LogFlags

Logger flags

Constructors

LogFlags
- log_default_user_context :: SDocContext
- log_default_dump_context :: SDocContext
- log_dump_flags :: !EnumSet DumpFlag
  Dump flags
- log_show_caret :: !Bool
  Show caret in diagnostics
- log_diagnostics_as_json :: !Bool
  Format diagnostics as JSON
- log_show_warn_groups :: !Bool
  Show warning flag groups
- log_enable_timestamps :: !Bool
  Enable timestamps
- log_dump_to_file :: !Bool
  Enable dump to file
- log_dump_dir :: !Maybe FilePath
  Dump directory
- log_dump_prefix :: !FilePath
  Normal dump path ("basename.")
- log_dump_prefix_override :: !Maybe FilePath
  Overriden dump path
- log_with_ways :: !Bool
  Use different dump files names for different ways
- log_enable_debug :: !Bool
  Enable debug output
- log_verbosity :: !Int
  Verbosity level
- log_ways :: !Maybe Ways
  Current ways (to name dump files)

valuedefaultLogFlags :: LogFlags

Default LogFlags

valuelog_dopt :: DumpFlag -> LogFlags -> Bool

Test if a DumpFlag is enabled

valuelog_set_dopt :: DumpFlag -> LogFlags -> LogFlags

Enable a DumpFlag

valuesetLogFlags :: Logger -> LogFlags -> Logger

Set LogFlags

valueupdateLogFlags :: Logger -> (LogFlags -> LogFlags) -> Logger

Update LogFlags

valuelogFlags :: Logger -> LogFlags

Logger flags

valuelogHasDumpFlag :: Logger -> DumpFlag -> Bool

Test if a DumpFlag is set

valuelogVerbAtLeast :: Logger -> Int -> Bool

Test if verbosity is >= to the given value

Logging

9 declarations

valueputLogMsg :: Logger -> LogAction

Log something

valuedefaultLogAction :: LogAction

The default LogAction prints to stdout and stderr.

To replicate the default log action behaviour with different out and err handles, see defaultLogActionWithHandles.

valuedefaultLogActionWithHandles

:: Handle
Handle for standard output
-> Handle
Handle for standard errors
-> LogAction

The default LogAction parametrized over the standard output and standard error handles. Allows clients to replicate the log message formatting of GHC with custom handles.

valuedefaultLogJsonAction :: LogJsonAction

valuedefaultLogActionHPrintDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO ()

Like defaultLogActionHPutStrDoc but appends an extra newline.

valuedefaultLogActionHPutStrDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO ()

The boolean arguments let's the pretty printer know if it can optimize indent by writing ascii ' ' characters without going through decoding.

valuelogMsg :: Logger -> MessageClass -> SrcSpan -> SDoc -> IO ()

Log something

valuelogJsonMsg :: ToJson a => Logger -> MessageClass -> a -> IO ()

valuelogDumpMsg :: Logger -> String -> SDoc -> IO ()

Log a dump message (not a dump file)

Dumping

7 declarations

valuedefaultDumpAction :: DumpCache -> LogAction -> DumpAction

Default action for dumpAction hook

valueputDumpFile :: Logger -> DumpAction

Dump something

valueputDumpFileMaybe

:: Logger
-> DumpFlag
-> String
-> DumpFormat
-> SDoc
-> IO ()

Dump if the given DumpFlag is set

valueputDumpFileMaybe'

:: Logger
-> NamePprCtx
-> DumpFlag
-> String
-> DumpFormat
-> SDoc
-> IO ()

Dump if the given DumpFlag is set

Unlike putDumpFileMaybe, has a NamePprCtx argument

valuewithDumpFileHandle

:: DumpCache
-> LogFlags
-> DumpFlag
-> Maybe Handle -> IO ()
-> IO ()

Run an action with the handle of a DumpFlag if we are outputting to a file, otherwise Nothing.

valuetouchDumpFile :: Logger -> DumpFlag -> IO ()

Ensure that a dump file is created even if it stays empty

valuelogDumpFile

:: Logger
-> PprStyle
-> DumpFlag
-> String
-> DumpFormat
-> SDoc
-> IO ()

Dump something

Tracing

5 declarations

valuedefaultTraceAction :: TraceAction a

Default action for traceAction hook

valueputTraceMsg :: Logger -> TraceAction a

Trace something

valueloggerTraceFlushUpdate :: Logger -> (IO () -> IO ()) -> Logger

Set the trace flushing function

The currently set trace flushing function is passed to the updating function

valueloggerTraceFlush :: Logger -> IO ()

Calls the trace flushing function

valuelogTraceMsg :: Logger -> String -> SDoc -> a -> a

Log a trace message