compiler/utils/debugutils

    Dark Mode
Search:
  Source   Edit

Utilities to help with debugging nimskull compiler.

Experimental API, subject to change.

Types

CompilerTrace = object
  instLoc*: InstantiationInfo
  case kind*: CompilerTraceKind
  of compilerTraceStep:
      semstep*: DebugSemStep

  of compilerTraceLine, compilerTraceStart:
      ctraceData*: tuple[level: int, entries: seq[StackTraceEntry]]

  of compilerTraceDefined, compilerTraceUndefined:
      srcLoc*: TLineInfo

  of compilerTraceEnd:
      nil
  Source   Edit 
CompilerTraceKind = enum
  compilerTraceStep, compilerTraceLine, compilerTraceStart, compilerTraceEnd,
  compilerTraceDefined, compilerTraceUndefined
  Source   Edit 
DebugCallableCandidate = object
  state*: string
  callee*: PType
  calleeSym*: PSym
  calleeScope*: int
  call*: PNode
  error*: SemCallMismatch
stripped down version of sigmatch.TCandidate   Source   Edit 
DebugSemStep = object
  direction*: DebugSemStepDirection
  level*: int
  name*: string
  node*: PNode               ## Depending on the step direction this field stores
                             ## either input or output node
  steppedFrom*: InstantiationInfo
  sym*: PSym
  case kind*: DebugSemStepKind
  of stepIdentToSym:
      ident*: PIdent

  of stepNodeTypeToType, stepTypeTypeToType:
      typ*: PType
      typ1*: PType

  of stepNodeFlagsToNode:
      flags*: TExprFlags

  of stepNodeSigMatch, stepResolveOverload:
      filters*: TSymKinds
      candidate*: DebugCallableCandidate
      errors*: seq[SemCallMismatch]

  else:
      nil
  Source   Edit 
DebugSemStepDirection = enum
  semstepEnter, semstepLeave
  Source   Edit 
DebugSemStepKind = enum
  stepNodeToNode, stepNodeToSym, stepIdentToSym, stepSymNodeToNode,
  stepNodeFlagsToNode, stepNodeTypeToType, stepTypeTypeToType,
  stepResolveOverload, stepNodeSigMatch, stepWrongNode, stepError, stepTrack
  Source   Edit 
StepParams = object
  c*: ConfigRef
  kind*: DebugSemStepKind
  indentLevel*: int
  action*: string
  info*: InstantiationInfo
Parameters necessary to construct new step of the execution tracing.   Source   Edit

Procs

proc isCompilerDebug(conf: ConfigRef): bool {.inline, ...raises: [], tags: [].}

Provides a simple way for user code to enable/disable logging in the compiler in a granular way. This can then be used in the compiler as follows:

if conf.isCompilerDebug():
  echo n.sym.typ.len

Example region to trace:

proc main =
  echo 2
  {.define(nimCompilerDebug).}
  echo 3.5 # code section in which `isCompilerDebug` will be true
  {.undef(nimCompilerDebug).}
  echo 'x'

  Source   Edit 
proc isCompilerTraceDebug(conf: ConfigRef): bool {....raises: [], tags: [].}
  Source   Edit 
proc outputTrace(conf: ConfigRef; t: CompilerTrace) {.
    ...raises: [KeyError, OSError, IOError, ValueError, Exception],
    tags: [ReadDirEffect, WriteDirEffect, WriteIOEffect, RootEffect].}
outputs the CompilerTrace to stdout or the file is specified   Source   Edit 
proc stepParams(c: ConfigRef; kind: DebugSemStepKind; indentLevel: int;
                action: string): StepParams {....raises: [], tags: [].}
  Source   Edit

Templates

template addInNimDebugUtils(c: ConfigRef; action: string)
add tracing to procs as a stop gap measure, not favour using one that provides more output for various parts   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; id: PIdent;
                            resSym: PSym)
add tracing to procs that are primarily PIdent -> PSym   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; n, r: PNode)
add tracing to procs that are primarily PNode -> PNode, and can determine the type   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; n, r: PNode;
                            flags: TExprFlags)
add tracing to procs that are primarily PNode -> PNode, with expr flags and can determine the type   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; n: PNode;
                            filter: TSymKinds; e: var seq[SemCallMismatch];
                            res: typed)
add tracing to procs that are primarily PNode -> TCandidate, looking for a candidate callable   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; n: PNode;
                            prev, r: PType)
add tracing to procs that are primarily PNode, PType|nil -> PType, determining a type node, with a possible previous type.   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; n: PNode; res: typed)
add tracing to procs that are primarily PNode -> TCandidate, looking for a candidate callable   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; n: PNode; resSym: PSym)
add tracing to procs that are primarily PNode -> PSym   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; s: PSym; n: PNode;
                            res: PNode)
add tracing to procs that are primarily PSym, PNode -> PNode, such as applying pragmas to a symbol   Source   Edit 
template addInNimDebugUtils(c: ConfigRef; action: string; x, y, r: PType)
add tracing to procs that are primarily PType, PType -> PType, looking for a common type   Source   Edit 
template addInNimDebugUtilsError(c: ConfigRef; n, e: PNode)
add tracing error generation PNode -> PNode   Source   Edit 
template frameMsg(c: ConfigRef; info: TLineInfo)
  Source   Edit 
template frameMsg(c: ConfigRef; n: PNode)
  Source   Edit 
template traceEnterIt(loc: InstantiationInfo; params: StepParams; body: untyped): untyped
Convenience wrapper around the traceStepImpl. If called from user code templateDepth parameter must be specified as well - it controls depth of the template instantiation location that is need to be accounted for. With current implementation of the debugutils this value is set to -5 (instDepth default), for your code it might be different (-2 when called directly and -1 for each wrapper template level).   Source   Edit 
template traceLeaveIt(loc: InstantiationInfo; params: StepParams; body: untyped): untyped
Convenience wrapper for traceStepImpl - for mode details see the traceEnterIt and traceStepImpl documentation.   Source   Edit 
template traceStepImpl(params: StepParams; stepDirection: DebugSemStepDirection;
                       body: untyped)
Construct and write debug step report using given parameters. Mutable it: DebugSemStep is injected and is accessible in the body that is passed to the template. stepDirection is assigned to the contructed step .direction field.   Source   Edit

Made with Nim. Generated: 2024-12-20 00:00:00 UTC