Hacking Xconq - Debugging

Go to the first, previous, next, last section, table of contents.

## Debugging

Xconq is both complicated and evolving. Therefore, it includes a debugging infrastructure. The code is ifdef'ed with the flag `DEBUGGING` so as to allow removal for "production" versions, although in practice the size reduction seems minor.

There are several builtin flags available for dynamic control of debugging output, and printf macros to go with them.

`Debug`
  The global flag `Debug` is for generic debug output, primarily kernel-oriented. The macro `Dprintf` tests it before printing, the command line flag `-D` sets it, and the command `DD` toggles it during the game.
`DebugM`
  This flag controls the debugging output for AIs and planning. `DMprintf` is the printing macro, `-DM` sets from the command line, and the command `DM` toggles.
`DebugG`
  This flag controls debugging output for interfaces. `DGprintf` is the printing macros, `-DG` sets from the command line, and `DG` is the toggling command.

It may also be useful to change interface behavior when debugging is enabled. For instance, you can display internal unit id in closeups, toplines, etc, in addition to the usual unit info (which may not identify a unit uniquely). Or you can make the interface display additional guides or bounding boxes to show where drawing is happening or not happening.

Although Xconq has been liberally sprinkled with debugging output, in this modern age of computing, powerful source-level debuggers are widely available, and there is no good reason to add debugging code to do a job that could be done by the debugger. Xconq debugging output is mainly designed to be useful for understanding average behavior, changes over time, and "high-level transients" such as thrashing in plan or task execution; information that is difficult to collect using only a debugger. When adding new debug output, you should keep this principle in mind. Also, be aware that some of the automated testing scripts enable debug output, so if you add something that is uselessly voluminous, testing output may fill your disk prematurely!

Another principle to use in designing debug output is to try to make each line self-contained. The output may run to thousands of lines, and tools like grep can be very useful filters, if the output is correctly formatted. For instance, the function `unit_desig` will produce a string that includes a unit's side, type, id, and position in a fixed format, which makes it easy to find the unit in debug output and then track its activities.

Go to the first, previous, next, last section, table of contents.