GHC.Utils.Logger

ghc-9.4.0.20220501: The GHC API

Safe Haskell | Safe-Inferred
Language | Haskell2010

GHC.Utils.Logger

Contents

- Logger setup
  - Hooks
  - Flags
- Logging
- Dumping
- Tracing

Description

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 suppors LogFlags: basically a subset of the command-line flags that control the logger behaviour at a higher level than hooks.

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

Synopsis

- data Logger
- class HasLogger m where
  - getLogger :: m Logger
- class ContainsLogger t where
  - extractLogger :: t -> Logger
- initLogger :: IO Logger
- type LogAction = LogFlags -> MessageClass -> SrcSpan -> SDoc -> IO ()
- type DumpAction = LogFlags -> PprStyle -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()
- type TraceAction a = LogFlags -> String -> SDoc -> a -> a
- data DumpFormat
  - = FormatHaskell
  - | FormatCore
  - | FormatSTG
  - | FormatByteCode
  - | FormatCMM
  - | FormatASM
  - | FormatC
  - | FormatLLVM
  - | FormatText
- popLogHook :: Logger -> Logger
- pushLogHook :: (LogAction -> LogAction) -> Logger -> Logger
- popDumpHook :: Logger -> Logger
- pushDumpHook :: (DumpAction -> DumpAction) -> Logger -> Logger
- popTraceHook :: Logger -> Logger
- pushTraceHook :: (forall a. TraceAction a -> TraceAction a) -> Logger -> Logger
- makeThreadSafe :: Logger -> IO Logger
- data LogFlags = LogFlags {
  - log_default_user_context :: SDocContext
  - log_default_dump_context :: SDocContext
  - log_dump_flags :: !(EnumSet DumpFlag)
  - log_show_caret :: !Bool
  - log_show_warn_groups :: !Bool
  - log_enable_timestamps :: !Bool
  - log_dump_to_file :: !Bool
  - log_dump_dir :: !(Maybe FilePath)
  - log_dump_prefix :: !FilePath
  - log_dump_prefix_override :: !(Maybe FilePath)
  - log_enable_debug :: !Bool
  - log_verbosity :: !Int
  }
- defaultLogFlags :: LogFlags
- log_dopt :: DumpFlag -> LogFlags -> Bool
- log_set_dopt :: DumpFlag -> LogFlags -> LogFlags
- setLogFlags :: Logger -> LogFlags -> Logger
- updateLogFlags :: Logger -> (LogFlags -> LogFlags) -> Logger
- logFlags :: Logger -> LogFlags
- logHasDumpFlag :: Logger -> DumpFlag -> Bool
- logVerbAtLeast :: Logger -> Int -> Bool
- jsonLogAction :: LogAction
- putLogMsg :: Logger -> LogAction
- defaultLogAction :: LogAction
- defaultLogActionHPrintDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO ()
- defaultLogActionHPutStrDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO ()
- logMsg :: Logger -> MessageClass -> SrcSpan -> SDoc -> IO ()
- logDumpMsg :: Logger -> String -> SDoc -> IO ()
- defaultDumpAction :: DumpCache -> LogAction -> DumpAction
- putDumpFile :: Logger -> DumpAction
- putDumpFileMaybe :: Logger -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()
- putDumpFileMaybe' :: Logger -> PrintUnqualified -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()
- withDumpFileHandle :: DumpCache -> LogFlags -> DumpFlag -> (Maybe Handle -> IO ()) -> IO ()
- touchDumpFile :: Logger -> DumpFlag -> IO ()
- logDumpFile :: Logger -> PprStyle -> DumpFlag -> String -> DumpFormat -> SDoc -> IO ()
- defaultTraceAction :: TraceAction a
- putTraceMsg :: Logger -> TraceAction a
- loggerTraceFlushUpdate :: Logger -> (IO () -> IO ()) -> Logger
- loggerTraceFlush :: Logger -> IO ()
- logTraceMsg :: Logger -> String -> SDoc -> a -> a

# Documentation

data Logger Source #

class HasLogger m where Source #

Methods

getLogger :: m Logger Source #

#### Instances

Instances details

HasLogger LlvmM Source # |
Instance details Defined in GHC.CmmToLlvm.Base Methods getLogger :: LlvmM Logger Source #
HasLogger CoreM Source # |
Instance details Defined in GHC.Core.Opt.Monad Methods getLogger :: CoreM Logger Source #
HasLogger SimplM Source # |
Instance details Defined in GHC.Core.Opt.Simplify.Monad Methods getLogger :: SimplM Logger Source #
HasLogger Hsc Source # |
Instance details Defined in GHC.Driver.Env.Types Methods getLogger :: Hsc Logger Source #
HasLogger Ghc Source # |
Instance details Defined in GHC.Driver.Monad Methods getLogger :: Ghc Logger Source #
ContainsLogger env => HasLogger (IOEnv env) Source # |
Instance details Defined in GHC.Data.IOEnv Methods getLogger :: IOEnv env Logger Source #
MonadIO m => HasLogger (GhcT m) Source # |
Instance details Defined in GHC.Driver.Monad Methods getLogger :: GhcT m Logger Source #

class ContainsLogger t where Source #

Methods

extractLogger :: t -> Logger Source #

#### Instances

Instances details

ContainsLogger (Env gbl lcl) Source # |
Instance details Defined in GHC.Tc.Types Methods extractLogger :: Env gbl lcl -> Logger Source #

# Logger setup

initLogger :: IO Logger Source #

type LogAction = LogFlags -> MessageClass -> SrcSpan -> SDoc -> IO () Source #

type DumpAction = LogFlags -> PprStyle -> DumpFlag -> String -> DumpFormat -> SDoc -> IO () Source #

type TraceAction a = LogFlags -> String -> SDoc -> a -> a Source #

data DumpFormat Source #

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
FormatText | Unstructured dump

#### Instances

Instances details

Show DumpFormat Source # |
Instance details Defined in GHC.Utils.Logger Methods showsPrec :: Int -> DumpFormat -> ShowS Source # show :: DumpFormat -> String Source # showList :: [DumpFormat] -> ShowS Source #
Eq DumpFormat Source # |
Instance details Defined in GHC.Utils.Logger Methods (==) :: DumpFormat -> DumpFormat -> Bool # (/=) :: DumpFormat -> DumpFormat -> Bool #

## Hooks

popLogHook :: Logger -> Logger Source #

Pop a log hook

pushLogHook :: (LogAction -> LogAction) -> Logger -> Logger Source #

Push a log hook

popDumpHook :: Logger -> Logger Source #

Pop a dump hook

pushDumpHook :: (DumpAction -> DumpAction) -> Logger -> Logger Source #

Push a dump hook

popTraceHook :: Logger -> Logger Source #

Pop a trace hook

pushTraceHook :: (forall a. TraceAction a -> TraceAction a) -> Logger -> Logger Source #

Push a trace hook

makeThreadSafe :: Logger -> IO Logger Source #

Make the logger thread-safe

## Flags

data LogFlags Source #

Logger flags

Constructors

LogFlags |
Fields 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_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_enable_debug :: !Bool Enable debug output log_verbosity :: !Int Verbosity level

defaultLogFlags :: LogFlags Source #

Default LogFlags

log_dopt :: DumpFlag -> LogFlags -> Bool Source #

Test if a DumpFlag is enabled

log_set_dopt :: DumpFlag -> LogFlags -> LogFlags Source #

Enable a DumpFlag

setLogFlags :: Logger -> LogFlags -> Logger Source #

Set LogFlags

updateLogFlags :: Logger -> (LogFlags -> LogFlags) -> Logger Source #

Update LogFlags

logFlags :: Logger -> LogFlags Source #

Logger flags

logHasDumpFlag :: Logger -> DumpFlag -> Bool Source #

Test if a DumpFlag is set

logVerbAtLeast :: Logger -> Int -> Bool Source #

Test if verbosity is >= to the given value

# Logging

jsonLogAction :: LogAction Source #

putLogMsg :: Logger -> LogAction Source #

Log something

defaultLogAction :: LogAction Source #

defaultLogActionHPrintDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO () Source #

Like `defaultLogActionHPutStrDoc` but appends an extra newline.

defaultLogActionHPutStrDoc :: LogFlags -> Bool -> Handle -> SDoc -> IO () Source #

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

logMsg :: Logger -> MessageClass -> SrcSpan -> SDoc -> IO () Source #

Log something

logDumpMsg :: Logger -> String -> SDoc -> IO () Source #

Log a dump message (not a dump file)

# Dumping

defaultDumpAction :: DumpCache -> LogAction -> DumpAction Source #

Default action for `dumpAction` hook

putDumpFile :: Logger -> DumpAction Source #

Dump something

putDumpFileMaybe :: Logger -> DumpFlag -> String -> DumpFormat -> SDoc -> IO () Source #

Dump if the given DumpFlag is set

putDumpFileMaybe' :: Logger -> PrintUnqualified -> DumpFlag -> String -> DumpFormat -> SDoc -> IO () Source #

Dump if the given DumpFlag is set

Unlike `putDumpFileMaybe`, has a PrintUnqualified argument

withDumpFileHandle :: DumpCache -> LogFlags -> DumpFlag -> (Maybe Handle -> IO ()) -> IO () Source #

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

touchDumpFile :: Logger -> DumpFlag -> IO () Source #

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

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

Dump something

# Tracing

defaultTraceAction :: TraceAction a Source #

Default action for `traceAction` hook

putTraceMsg :: Logger -> TraceAction a Source #

Trace something

loggerTraceFlushUpdate :: Logger -> (IO () -> IO ()) -> Logger Source #

Set the trace flushing function

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

loggerTraceFlush :: Logger -> IO () Source #

Calls the trace flushing function

logTraceMsg :: Logger -> String -> SDoc -> a -> a Source #

Log a trace message