Debug code mapping RFC

[MiranDMC]

Idea

Be able to link compiled script's offset to it's origination line in source script.

Motivation

Binary to source mapping will enable implementation of:

• more detailed compilation error messages
• debugger for scripts other than main.scm
• debugger for scripts using $INCLUDE directive
• runtime error messages in CLEO5 including exact script line
• script execution log matching actual script source code in CLEO5 (improved SrcLog)

Execution

• During preprocessing stage store information about current source file and the line number
• During compilation process, every time file/line marker from previous stage is encountered, add current compiled code offset entry to that marker.
• Generate JSON file containing original source files and generated file-line markers with their code offsets.

File format

JSON seems to be most easy to output and integrate in other tools format.
Compiling script in SB should produce (except compiled script) single debug mapping JSON file.
Proposed name is script_name.debug.json. Debug should be obvious suggestion this is not file meant to be released with script.
File should be copied along the resulting script into game directory, if such option was used in SB.

Debug file contents

Output json file should contain:

• Compilation date
• SB version
• used mode information
• list of source files used during compilation:
  • name of the file, including path relative to main/project script file
  • information if this is the main project file (the one that was compiled in SB)
  • (?) hash of the file
  • unique file identifier/index within this debug file
  • source file contents split into array of lines
• information about compiled script:
  • size of file
  • size of code block
  • hash of the code block
  • array of code mappings, constructed of:
    • binary code offset
    • unique identifier of source file
    • source file line number
    • offset within source line (in cases where there is multiple opcodes in single line)