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.cssets the environment variablesMONOMOD_DEBUGIL_RELATIVEandMONOMOD_DEBUGIL_SKIP_MAXSTACK, butDebugILGeneratorreads the switchesDebugIL_RelativeandDebugIL_SkipMaxStack. AMONOMOD_environment variable becomes a switch with exactly the rest of its name, and switch names are case-sensitive, soDEBUGIL_RELATIVEnever matchesDebugIL_Relative. To get the behavior, set the correctly cased variables yourself before running the tool:MONOMOD_DebugIL_Relative=1andMONOMOD_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 (seeMONOMOD_DEBUG_FORMATon the Patcher page). __AssemblyInfo__.il: assembly-level metadata.- One folder per type, following its namespace and nesting (
Celeste/Player/), containing__TypeInfo__.iland one<MethodName>.ilfile 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
- Run
MonoMod.DebugIL Game.exe. - Replace the game's assembly with the rewritten one from
MMDBGIL_Game.exe/(keep a backup), or load it from there. - Start the game under a debugger (or attach to it), open the
.ilfile of the method you care about, and set a breakpoint on an instruction line.