Editing MacsBug Reference and Debugging Guide

The '''''MacsBug Reference and Debugging Guide''''' is '''Apple Computer, Inc.'s''' developer manual for '''MacsBug 6.2''', published by '''Apple Developer Press, 1995''' (© 1994, 1990 Apple Computer, Inc.). '''410 pages''', with full bookmarks and a text layer.

MacsBug is Apple's low-level assembly-language debugger for the 68 K Macintosh — the tool that catches a machine at the moment it crashes, below the level any application-level debugger reaches.

== Contents ==
* Preface: About This Manual (p. xxi)
* '''1. MacsBug and Low-Level Debugging''' (p. 1) — error handling on the Macintosh, why low-level debugging, new features in 6.2
* '''2. Getting Started''' (p. 9) — installing MacsBug, '''installing under A/UX''', displaying MacsBug on a different monitor (System 3.2–6.x and System 7.0 differ), the Debugger Prefs file, the MacsBug display regions (command line, PC, output, status/stack/register), '''invoking MacsBug''' — the programmer's switch, an 'FKEY' resource, or <code>DebugStr</code> from source
* '''3. An Assembly-Language Primer''' (p. 33) — 68 K instruction syntax and every addressing mode
* '''4. Macintosh Memory Organization''' (p. 65) — the memory map and its regions, '''using low-memory globals to draw a memory map''', memory management under System 7, 32-bit addressing, virtual memory, registers, templates, the heap and heap blocks, and '''detecting a corrupted heap'''
* '''5–6''' — the stack and A-traps, '''Macintosh interrupts''' and code that runs at interrupt time, VBL tasks, the A-trap action table, the file system (drive queue, file control blocks, file I/O queue)
* '''7. Debugging Strategies''' (p. 163) — before the crash and after it; the named failure modes "The Deep Freeze", "The Restart Surprise", "Nasty Pointers", "No Room to Maneuver"
* '''8''' — macros, <code>'mxbm'</code> resources, dcmds and how to build one
* '''9. MacsBug Commands''' (p. 207) — the full command reference, alphabetically from ATB

== What it is good for on this wiki ==
'''A Macintosh that crashes reproducibly at a known address is diagnosable with this book and a keyboard, without opening the case.''' Chapter 7 is the part worth reading: it separates a software crash from a hardware fault by what the machine does at the moment of failure, which is exactly the question a repairer needs answered before desoldering anything.

Chapter 4's memory map and low-memory globals are also the reference behind the address interpretation used in [[Sad Mac Error Codes]] — though the Sad Mac codes themselves come from the ROM, not from MacsBug.

== What it does not contain ==
'''No hardware information of any kind.''' No schematic, no part number, no component value, no voltage, no connector pinout. It is a software debugger manual. Do not cite it for a hardware figure.

== Related pages ==
* [[Sad Mac Error Codes]] · [[Sad Mac Decoder]] · [[Diagnostic Serial Console]]
* [[:Category:Apple Programming Documentation]]
* [[Programmers Guide to MPW 1990]] — Apple's command-line development environment, the toolchain MacsBug was used beside (that page's file was never uploaded)
* [[Programming For System 7 1991]] — the System 7 memory model this manual's chapter 4 describes from the debugger's side

<pdf> File:MacsBug Reference and Debugging Guide.pdf </pdf>

Download the MacsBug Reference and Debugging Guide here: [[:File:MacsBug Reference and Debugging Guide.pdf|MacsBug Reference and Debugging Guide.pdf]] (1.5 MB)

[[Category:Apple Documentation]]