DebugIL (MonoMod.DebugIL)

MonoMod.DebugIL makes third-party assemblies debuggable at the IL level. It writes the IL of every method to text files and rewrites the assembly so that its debug symbols point at those files, one sequence point per instruction. Attach Visual Studio or another debugger and you can step through a game's IL instruction by instruction, even without its source code. This page covers the command line, the output layout, and the options.

Command Line

MonoMod.DebugIL [--relative] [--skip-maxstack] [--diff] <input assembly> [<output directory>]
Option Intended effect
--relative Write instructions in a relative form (instr.ToRelativeString()), so dumps of two versions of an assembly differ less.
--skip-maxstack Do not write the .maxstack line for each method.
--diff Both of the above, for diff-friendly output.

Warning: In the current source, these three options appear to have no effect. Program.cs sets the environment variables MONOMOD_DEBUGIL_RELATIVE and MONOMOD_DEBUGIL_SKIP_MAXSTACK, but DebugILGenerator reads the switches DebugIL_Relative and DebugIL_SkipMaxStack. A MONOMOD_ environment variable becomes a switch with exactly the rest of its name, and switch names are case-sensitive, so DEBUGIL_RELATIVE never matches DebugIL_Relative. To get the behavior, set the correctly cased variables yourself before running the tool: MONOMOD_DebugIL_Relative=1 and MONOMOD_DebugIL_SkipMaxStack=1.

The default output is a directory named MMDBGIL_<input file name> next to the input. If the last argument differs from the input, it is used as the output directory.

Warning: If the output directory already exists, it is deleted recursively (Clearing <path> is printed) before the new dump is written. Do not point it at a directory containing anything you want to keep.

Output

The output directory contains:

  • The rewritten assembly (same file name as the input), with a new DebuggableAttribute (Default | DisableOptimizations | EnableEditAndContinue) so the JIT does not optimize it, and debug symbols written by MonoMod's writer: PDB on Windows and MDB on other systems by default (see MONOMOD_DEBUG_FORMAT on the Patcher page).
  • __AssemblyInfo__.il: assembly-level metadata.
  • One folder per type, following its namespace and nesting (Celeste/Player/), containing __TypeInfo__.il and one <MethodName>.il file per method. Overloads are numbered: Update.il, Update.1.il, ... Characters that are invalid in file names are replaced with _.

Dumping runs in parallel tasks; progress is printed as [MonoMod] [DbgIlGen] <done> / <total> tasks finished.

Typical Workflow

  1. Run MonoMod.DebugIL Game.exe.
  2. Replace the game's assembly with the rewritten one from MMDBGIL_Game.exe/ (keep a backup), or load it from there.
  3. Start the game under a debugger (or attach to it), open the .il file of the method you care about, and set a breakpoint on an instruction line.

See Also