Debugger: Add dbg.logexec option to log debugger script execution output (fixes #1121)

[dionoid]

PR Description

Summary

This PR adds two new command line arguments that enhance Stella's debugger scripting capabilities:

1. -dbg.logexec - Enables logging of debugger script execution output to a file
2. -dbg.script - Specifies a custom script file to execute on debugger startup

These features make it possible to use Stella's debugger scripts in automated and headless workflows, where debugger UI output is not available.

This addresses feature request #1121 and is related to #509.

Motivation

Debugger scripts executed via the exec command currently write their output only to the debugger UI. This makes it difficult to:

• Run Stella in headless or automated environments (CI/CD, batch testing)
• Capture and parse script results programmatically
• Use debugger scripts for automated verification tasks (e.g. validating scanline counts)
• Specify one-off debug scripts

For example, a script that advances frames and prints _scanEnd cannot currently be validated without manual interaction.

Changes

New -dbg.logexec option

Added new command line argument dbg.logexec (default: false)

• Can be enabled via command line:

  -dbg.logexec 1
  -dbg.logexec true

• Also added accompanying debugger command logExec, which toggles exec script logging on/off in the interactive debugger

Logging behavior:
When enabled, all executed debugger commands and their results are written to:

[script_path].output.txt

Format:

• Command on one line
• Result on the following line(s)

Example output:

> frame #60
advanced 60 frame(s)
> joy0Fire 1
> joy0Fire 0
> frame #60
advanced 60 frame(s)
> print _scanEnd
CXBLPF|$100(R) / COLUP0|$100(W): $0106 %0000000100000110 #262
> saveSnap
> exitRom

Log write failures are non-blocking and emit a warning without interrupting script execution.

New -dbg.script parameter

Added command line parameter -dbg.script <file> to specify a custom script file to execute on debugger startup.

Execution order:

1. autoexec.script (if present)
2. [romname].script (if present)
3. Script specified by -dbg.script (if provided)
4. Built-in functions initialization

Use case:
Allows running temporary or session-specific debug scripts without modifying permanent autoexec.script or [romname].script files. Particularly useful for:

• One-off debugging sessions with custom setup
• Automated testing workflows that need specific breakpoints/watches
• Combining with -dbg.logexec for fully automated script execution and result capture

Script parsing improvements

• Lines starting with ; are treated as comments and skipped
• Empty or whitespace-only lines are ignored

Usage Examples

Basic script execution with logging

In debugger:

> logExec
logExec enabled
> exec test.script

Output written to: test.script.output.txt

Basic script execution with automatic logging

stella -dbg.logexec true -debug game.bin

In debugger:

exec test.script

Output written to: test.script.output.txt

Custom script on startup

stella -dbg.script /path/to/test.script game.bin

Automated testing workflow

# Combine both features for fully automated debugging
stella -dbg.script custom.script -dbg.logexec 1 -debug game.bin

This will:

1. Execute custom.script on debugger startup (after autoexec and romname scripts)
2. Log all script output to custom.script.output.txt
3. Allow programmatic validation of results

Files Modified

-dbg.logexec changes:

• src/emucore/Settings.cxx - Added parameter definition and help text
• src/debugger/DebuggerParser.cxx - Added logging functionality and comment parsing
• src/gui/DeveloperDialog.cxx - Added UI toggle for logExec
• docs/index.html - Added command line parameter documentation

-dbg.script changes:

• src/emucore/Settings.cxx - Added parameter definition and help text
• src/debugger/Debugger.cxx - Modified autoExec() to execute the specified script
• docs/index.html - Added command line parameter documentation
• docs/debugger.html - Updated Startup section with execution order details

Notes

These changes do not alter existing debugger behavior when the new options are disabled and are fully opt-in.

[thrust26]

Are you going to update the Debugger documentation too?

[dionoid]

Are you going to update the Debugger documentation too?

Yes, I just updated the Debugger documentation too. The logExec debug command works from the interactive debug UI, and also by setting the -dbg.logexec command line parameter.