Proposal: splitting Document.h/m into smaller files to ease reuse in other contexts

[jverkoey]

Context

I've been working on a tracing disassembler for Gameboy ROMs, with the primary goal being to help with the Link's Awakening disassembly project. The WIP tool is available at https://github.com/jverkoey/windfish.

I'd started dabbling with emulation to facilitate explorations, but as I dug into test ROMs I realized my time's better spent supporting + improving existing emulators and focusing on the disassembly tooling as a complement instead.

To that end, I'd like to propose a somewhat mechanical, but hopefully useful refactoring to Document.h/m.

Why is this needed?

I plan to integrate the Sameboy emulator into the Windfish disassembler so that the emulator can be synchronized with the disassembly view, something like so:

Screen.Recording.2021-01-13.at.1.34.53.AM.mov

As-is, Document.h/m is built under the assumption that everything is wired up to Interface Builder in a pre-determined manner. This makes it difficult to connect the emulator's behavior to different inputs, such as a step debugger or a source view. If the Document's model logic were separated from its view logic, it would be easier to reuse the model logic in different contexts such as the Windfish disassembler.

The proposed change

• All GB_gameboy_t-specific methods moved out to new classes.
  • Extract CallbackBridge from Document. #327 Where appropriate, C callbacks will be replaced with the more traditional delegate pattern using protocols. This will make it easier to integrate the emulator into other Objective-C or Swift source.
  • Anything related to emulation will be split out to separate classes that provide high level APIs for interacting with the GB_gameboy_t.
• Only view and document-specific logic remains in Document.h/m.
• No behavior is changed; this is a purely mechanical refactoring.

I'm writing this proposal with the hopes of getting confirmation that such a refactoring would be desired prior to investing significant time into it. If the maintainers would be open to such a change, I can send out a series of small, iterative PRs to perform the migration, or I can bulk everything into a single PR composed of many small commits if preferred.

[LIJI32]

Hi, I'm a bit curious about the end-goal. Which parts of the Cocoa frontend do you plan on using? I pretty much intended the C API to be the "official" API for SameBoy frontends, so deriving from the Cocoa frontend directly was never a use-case I expected.

[jverkoey]

The main things I'd like to reuse thus far are the running of the emulator on a background thread (the preRun, run, and postRun logic) and the feeding of audio samples to the audio client. Both of these code paths are fairly non-trivial so I want to find a way to reuse them without having to instantiate an entire Document type; windfish has its own document format because it manages a variety of disassembly configurations and source generation.

[jverkoey]

With the above in mind, perhaps the next step after the callback bridge is to provide an emulator runner + audio bridge API that extracts those two code paths into single reusable entities. What do you think?

[jverkoey]

Quick status update video of the integration:

shortened.mov

[jverkoey]

Call stack & undo now integrated as well. Video shows using the watch command to observe changes to a variable. Call stack is in lower-left corner.

short.mov