Sophie: xconq-7.5.0-1.20050612.5mdv2009.1 i586

xconq-7.5.0-1.20050612.5mdv2009.1.i586.rpm

<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.39
     from ./hacking.texi on 12 June 2005 -->

<TITLE>Hacking Xconq - Debugging</TITLE>
</HEAD>
<BODY>
Go to the <A HREF="hacking_1.html">first</A>, <A HREF="hacking_32.html">previous</A>, <A HREF="hacking_34.html">next</A>, <A HREF="hacking_35.html">last</A> section, <A HREF="hacking_toc.html">table of contents</A>.
<HR>


<H2><A NAME="SEC35" HREF="hacking_toc.html#SEC35">Debugging</A></H2>

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

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

</P>
<DL COMPACT>

<DT><CODE>Debug</CODE>
<DD>
The global flag <CODE>Debug</CODE> is for generic debug output, primarily
kernel-oriented.  The macro <CODE>Dprintf</CODE> tests it before printing, the
command line flag <CODE>-D</CODE> sets it, and the command <CODE>DD</CODE> toggles
it during the game.

<DT><CODE>DebugM</CODE>
<DD>
This flag controls the debugging output for AIs and planning.
<CODE>DMprintf</CODE> is the printing macro, <CODE>-DM</CODE> sets from the command
line, and the command <CODE>DM</CODE> toggles.

<DT><CODE>DebugG</CODE>
<DD>
This flag controls debugging output for interfaces.  <CODE>DGprintf</CODE> is
the printing macros, <CODE>-DG</CODE> sets from the command line, and
<CODE>DG</CODE> is the toggling command.

</DL>

<P>
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.

</P>
<P>
Although <I>Xconq</I> 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.  <I>Xconq</I> 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!

</P>
<P>
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 <CODE>unit_desig</CODE> 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.

</P>

<HR>
Go to the <A HREF="hacking_1.html">first</A>, <A HREF="hacking_32.html">previous</A>, <A HREF="hacking_34.html">next</A>, <A HREF="hacking_35.html">last</A> section, <A HREF="hacking_toc.html">table of contents</A>.
</BODY>
</HTML>