Home /Modules/debugger/TUTORIAL.md

TUTORIAL.md

debugger/TUTORIAL.md · 340 line(s) · markdown

SLeeLa Debugger — User Tutorial

Version: 0.8.0

Purpose

This tutorial takes a new SLeeLa user through ten progressively deeper steps for understanding and using the debugger and its decompiler-oriented inspection workflow.

Important: The debugger's current portable/model capabilities are not the same thing as a completed native decompiler. Native execution, symbol recovery, DWARF/PDB processing, and advanced reverse-engineering features must be verified through their corresponding backend and conformance tests before being treated as production capabilities.

Step 1 — Understand the Debugger

Start with the basic mental model:

Target → Native Backend → DebugEngine → DebugSession/Event Bus → Actions → Diagnostics/Evidence → Tests/UI

The debugger observes and controls a program through explicit contracts. It should never silently claim that an operation is supported when only the data model exists.

Learn these concepts first:

Read:

Step 2 — Build the Debugger

From the debugger/ directory:

make

Run the complete test path:

make test

Run only the conformance suite:

make conformance

Clean generated executables:

make clean

A successful build proves that the selected source set compiles. A successful portable/conformance test does not by itself prove native Linux, macOS, or Windows debugging.

Step 3 — Learn Sessions and Stops

A debugging session has a lifecycle:

  1. Launch or attach to a target.
  2. Establish the session identity.
  3. Set or discover debugging controls.
  4. Resume execution.
  5. Receive an event.
  6. Record why execution stopped.
  7. Inspect program state.
  8. Continue, step, or terminate.
  9. Preserve evidence.

The important question is not merely “did it stop?” but:

Why did it stop, what evidence proves that, and what program state was observed?

Use the Stop Record and Evidence Bundle concepts when reading debugger output.

Step 4 — Use Breakpoints and Watchpoints

A breakpoint asks the debugger to stop execution at a defined location.

A watchpoint asks it to stop when a memory location is accessed according to a specified access policy.

Understand the difference between:

Example conceptual workflow:

launch target
    ↓
set breakpoint
    ↓
continue
    ↓
breakpoint event
    ↓
inspect frame/registers/memory
    ↓
record evidence

Do not interpret a portable breakpoint record as proof that the operating system inserted a native breakpoint.

Step 5 — Read Program State

Once stopped, work outward from the current execution point.

Inspect:

  1. Current thread.
  2. Current stack frame.
  3. Calling frames.
  4. Registers.
  5. Relevant memory.
  6. Symbols and source location.
  7. Loaded modules.
  8. Exception or signal information.

The goal is to reconstruct a defensible picture of the program state rather than relying on a single line of output.

Native register, memory, stack, and symbol availability is backend-specific.

Step 6 — Understand the Decompiler Boundary

The debugger and a decompiler answer related but different questions.

A debugger asks:

What is the program doing right now?

A decompiler asks:

What higher-level structure can reasonably be reconstructed from compiled code?

A decompiler workflow can involve:

SLeeLa should preserve the distinction between observed facts, recovered symbols, and inferred structure.

Step 7 — Trace Decompiled Functions Back to Evidence

When examining a recovered function, associate the decompiler result with evidence wherever possible.

A useful chain is:

binary
  ↓
module identity
  ↓
address/range
  ↓
function
  ↓
instruction/control-flow evidence
  ↓
symbol/source information
  ↓
debugger runtime observation
  ↓
diagnostic evidence

When source information is unavailable, label the result accordingly.

Do not present inferred names, types, or control flow as original source unless the evidence actually supports that conclusion.

Step 8 — Use Diagnostics and Reproduction

When something fails, preserve the evidence.

The DiagnosticsEngine supports the conceptual record of:

Use the .sleela-debug artifact model to keep a session reproducible and inspectable.

A useful debugging report should answer:

Step 9 — Apply the Conformance and Security Rules

Before calling a debugger feature complete, move it through:

Model → Implement → Integrate → Verify

The Conformance Suite exists to prevent a documented interface from being mistaken for a finished native capability.

Security is equally important.

Treat:

as potentially sensitive operations.

Never use debugger expressions as an accidental shell.

Never treat an untrusted debugging artifact as trustworthy merely because it has the expected file extension.

Read:

Step 10 — Grow From User to Debugger Developer

After mastering the first nine steps, begin contributing new capabilities.

For every proposed feature, ask:

1. Model

What data, states, errors, and contracts are required?

2. Implement

Does the code actually perform the operation?

3. Integrate

Does it connect correctly to the backend, DebugEngine, session, diagnostics, and user interface?

4. Verify

Are there executable positive, negative, regression, security, and platform-aware tests?

For decompiler-oriented work, add evidence at every stage:

Input Binary
    ↓
Identity / Architecture
    ↓
Sections / Symbols
    ↓
Instructions
    ↓
Control Flow
    ↓
Functions
    ↓
Types / Variables
    ↓
Recovered Representation
    ↓
Runtime Validation
    ↓
Evidence / Report

The mature SLeeLa workflow is therefore not simply:

“Decompiler → output.”

It is:

“Input → analysis → evidence → reconstruction → debugger correlation → verification → report.”

Next Reading

After completing this tutorial, continue with:

Completion Check

A user has completed the tutorial when they can explain, without relying on undocumented behavior: