Created Debugging (markdown)

Debugging.md

@@ -0,0 +1,36 @@
+# Debugging
+
+Unfortunately, Retro68 doesn't include a proper debugger.
+
+## Common Problems
+
+If you find you don't even get to your `main` function, check your program's memory size.
+In the Finder, choose Get Info for your program and increase the "preferred" and "minimum" sizes. If that helps, include a `'SIZE'` resource in your program to set the "suggested" and "minimum" sizes automatically.
+
+If that's not the reason, it's *very* likely that you've run into a bug in Retro68... (open an issue!)
+
+## MacsBug
+The most important tool for debugging classic Mac applications is **MacsBug**:
+
+http://macintoshgarden.org/apps/macsbug-663
+
+It will run on real Macs and in minivmac; I haven't had much luck with Basilisk or SheepShaver.
+
+MacsBug is a low-level debugger. This means disassembly, hex, black magic, and a command line.
+There should still be tutorials floating around on the net, but to get started, you absolutely need to know two commands:
+
+* `g` - for "Go". Continue execution.
+* `es` - for "Exit to Shell". (Try to) exit the current program and get back to the finder.
+
+MacsBug will be triggered automatically whenever there is a crash in your program.
+In case of simple bugs, you might even see a function name displayed. (try the `sc' command to get a stack trace; it sometimes works!)
+
+You can also deliberately break into the debugger using two functions you can call from your program:
+* `Debugger();` - enter the debugger.
+* `DebugStr("\pHello, world.");` - enter the debugger and display the string.
+
+Have fun...
+
+## `fprintf` or `std::ofstream`
+
+Retro68's standard library support has huge holes, but you should be able to write log files to disk and see how far your program got.