Add debug line tables across backends

Cargo.toml

@@ -16,6 +16,7 @@ backend-cranelift = [
     "dep:cranelift-frontend",
     "dep:cranelift-module",
     "dep:cranelift-object",
+    "dep:gimli",
 ]
 backend-llvm = []
 inprocess-lld = []
@@ -38,6 +39,7 @@ cranelift-codegen = { version = "0.133.1", features = [
 cranelift-frontend = { version = "0.133.1", optional = true }
 cranelift-module = { version = "0.133.1", optional = true }
 cranelift-object = { version = "0.133.1", optional = true }
+gimli = { version = "0.33.0", features = ["write"], optional = true }
 object = "0.39.1"
 serde_json = "1.0"
 sha2 = "0.10"

README.md

@@ -185,12 +185,22 @@ small `wc`-style command-line program step by step.
 | `oscan app.osc --backend cranelift` | Select Cranelift explicitly |
 | `oscan app.osc --opt-level speed` | Favor generated-code speed over the default size profile |
 | `oscan app.osc --backend c` | Select the C backend explicitly |
+| `oscan app.osc --debuginfo line-tables` | Keep Oscan source locations for debugging |
 | `oscan --help` | Show every option |
 
 A release package contains one backend. If you request another one, Oscan tells
 you which package to install. `--opt-level size|speed` applies to LLVM and
 Cranelift generated code; the default is `size`.
 
+Debug information is opt-in: `--debuginfo none` is the default, while
+`--debuginfo line-tables` enables source breakpoints, stepping, stack
+symbolization, and imported-file locations without changing the selected
+optimization level. Oscan does not generate backend-independent local-variable
+or type descriptions at this level, although a C toolchain may include
+additional records. See
+[compiler technical details](docs/technical-details.md#debug-information) for
+backend and debugger-format notes.
+
 ## Examples
 
 Run any example with `oscan <path> --run`.

docs/guide.md

@@ -1060,6 +1060,13 @@ C is selected implicitly by `--emit-c`, `-o file.c`, and
 `--target riscv64|wasi`. LLVM IR output selects LLVM. For compatibility, an
 explicit `--native-target` without `--backend` selects Cranelift.
 
+All three backends accept `--debuginfo line-tables`. This keeps Oscan
+source-file and line mappings (including imported files), disables final
+stripping, and preserves stack-walking support without changing the backend's
+optimization level. The default is `--debuginfo none`. Line-table mode does not
+ask Oscan's native emitters to describe local variables or source types; a C
+toolchain may include additional records.
+
 LLVM provider lookup order:
 
 1. `OSCAN_LLVM_LIB` — absolute shared-library path

docs/spec/oscan-spec.md

@@ -2054,6 +2054,7 @@ oscan [OPTIONS] <file.osc>
 | `--emit-llvm-ir` | Emit textual LLVM IR to stdout (alias: `--emit-llvm`). Requires the LLVM backend and stops before object emission and linking. |
 | `--libc`        | Use hosted libc mode instead of freestanding mode. Enables access to standard C library functions. |
 | `--backend <name>` | Explicitly select `llvm` (direct IR plus in-process LLVM object code), `cranelift` (direct Cranelift AOT object code), or `c` (portability/reference/source backend), limited to the backends the build contains. `native` is a deprecated alias for `cranelift`. Without this option, a released single-backend package uses its own backend; a multi-backend build prefers LLVM on supported Windows/Linux hosts when a compatible provider is available, then Cranelift, then C. |
+| `--debuginfo <level>` | Debug information level: `none` (default) or `line-tables`. Line tables preserve Oscan file/line mappings for breakpoints, stepping, stack traces, and symbolization without changing optimization. Oscan does not generate or guarantee local-variable and type descriptions at this level; a C toolchain may include additional records. |
 | `--native-target <tag>` | Object target for `--backend llvm` and `--backend cranelift`. Supported: `host` (default), `linux-x86_64`, `windows-x86_64`, `linux-aarch64`, `linux-riscv64`. Provider target capabilities are checked before LLVM emission. |
 | `--target <arch>` | Cross-compile for target architecture (C backend only). Supported: `riscv64`, `wasi`. Without this flag, compiles for the host platform. |
 | `--extra-c <file>` | Extra C source file to compile and link (repeatable). Requires C compiler. |

docs/technical-details.md

@@ -47,6 +47,31 @@ Some output requests imply a backend:
 - `--libc`, `--extra-c`, and `--extra-cflags` do not by themselves select C,
   though they may require a C toolchain during the final build.
 
+## Debug information
+
+`--debuginfo none` is the release-compatible default. Opting into
+`--debuginfo line-tables` preserves Oscan source locations for source
+breakpoints, stepping, stack symbolization, and imported-file mappings. It does
+not change optimization. Oscan's native emitters do not describe local
+variables or source types at this level; a C toolchain may include additional
+records.
+
+| Backend | Line-table implementation |
+|---|---|
+| C | The generated translation unit uses `#line` directives that name the original `.osc` files. Clang uses `-gline-tables-only`, GCC uses `-g1`, and MSVC uses embedded `/Z7` records plus linker debug output (which can contain more than line tables). |
+| LLVM | Oscan emits `DICompileUnit`, `DIFile`, `DISubprogram`, and `DILocation` metadata directly in its LLVM IR with `LineTablesOnly` emission. |
+| Cranelift | Oscan interns Cranelift source locations, converts final machine-code ranges into DWARF line rows, and writes the required DWARF sections into the object. |
+
+Debug final links retain symbols and line sections instead of passing strip
+flags. Debug-mode C and native code also preserve frame pointers; unwind
+metadata is retained or generated where the backend supports it.
+
+On Windows, the C backend can produce a PDB through an MSVC-compatible
+toolchain. The LLVM and Cranelift object backends currently emit DWARF in COFF,
+not CodeView/PDB, so they require a debugger that understands DWARF-in-COFF.
+Native CodeView/PDB generation, optimized locals, and full type information are
+separate future tiers.
+
 ## Release packages
 
 Release contract schema 2 publishes one archive per platform/backend pair. It