Skip to main content

Compiler implementation guides

Guides for implementing ethdebug/format support in compilers.

Overview​

Compilers that want to support ethdebug/format need to emit several kinds of debug information alongside bytecode:

  1. Type information — Describe the types used in the program (see Types)
  2. Pointer information — Describe where variables are stored at runtime (see Pointers)
  3. Program information — Map each bytecode instruction back to source-level context (see Programs)
  4. Info/resources — Bundle everything together with compilation metadata (see Info)

Most compilers can add support incrementally:

  1. Start with types. Converting your compiler's internal type representations to ethdebug/format types is usually the most straightforward step.
  2. Add storage pointers. Many storage variables have statically known locations, making them a natural next step.
  3. Add memory/stack pointers. These often require tracking allocations during code generation.
  4. Add program annotations. Source mappings and variable scoping at each instruction typically requires the deepest compiler integration.

Output structure​

Compilers should emit an ethdebug/format/info/resources object containing shared resources (compilation, types, pointers), plus individual program objects alongside each bytecode artifact. See the Info concepts page for a sketch of how this fits into compiler JSON output.

Case study​

The BUG compiler is a small reference implementation that demonstrates the full integration:

  • Case Study: BUG — Walkthrough of how the BUG compiler generates types, pointers, and program annotations
  • BUG Playground — Interactive demo where you can compile BUG code and inspect the debug output