<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<html><head><title>
Allegro Manual: Debugging
</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="Content-Style-Type" content="text/css">
<link rel="stylesheet" title="Default" type="text/css" href="allegro.css"></head><body bgcolor=white text=black link="#0000ee" alink="#ff0000" vlink="#551a8b">
<h1><a name="Debugging">Debugging</a></h1>
<ul>
<li><a href="#al_assert">al_assert</a> — Asserts at the specified file and line number.
<li><a href="#al_trace">al_trace</a> — Outputs a debugging trace message.
<li><a href="#ASSERT">ASSERT</a> — Debugging helper macro to assert.
<li><a href="#register_assert_handler">register_assert_handler</a> — Registers a custom handler for assert failures.
<li><a href="#register_trace_handler">register_trace_handler</a> — Registers a custom handler for trace output.
<li><a href="#TRACE">TRACE</a> — Debugging helper macro to trace messages.
</ul>
<p>
There are three versions of the Allegro library: the normal optimised code,
one with extra debugging support, and a profiling version. See the platform
specific readme files for information about how to install and link with
these alternative libs. Although you will obviously want to use the
optimised library for the final version of your program, it can be very
useful to link with the debug lib while you are working on it, because this
will make debugging much easier, and includes assert tests that will help to
locate errors in your code at an earlier stage. Allegro also contains some
debugging helper functions:
<p><br>
<div class="al-api"><b>void <a name="ASSERT">ASSERT</a>(condition);</b></div><br>
Debugging helper macro. Normally compiles away to nothing, but if you
defined the preprocessor symbol DEBUGMODE before including Allegro headers,
it will check the supplied condition and call al_assert() if it fails,
whose default action is to stop the program and report the assert. You can
use this macro even when Allegro has not been initialised. Example:
<blockquote class="code"><pre>
#define DEBUGMODE
#include <allegro.h>
...
void my_blitter(<a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *source, int flags)
{
int some_variables;
<a href="#ASSERT" class="autotype" title="Debugging helper macro to assert.">ASSERT</a>(source != NULL);
<a href="#ASSERT" class="autotype" title="Debugging helper macro to assert.">ASSERT</a>(flags & GAME_RUNNING);
...
}</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_assert" title="Asserts at the specified file and line number.">al_assert</a>,
<a class="xref" href="#TRACE" title="Debugging helper macro to trace messages.">TRACE</a>,
<a class="xref" href="#register_assert_handler" title="Registers a custom handler for assert failures.">register_assert_handler</a>.</blockquote>
<blockquote class="eref"><em><b>Examples using this:</b></em>
<a class="eref" href="alleg046.html#expackf" title="Using custom PACKFILE vtables.">expackf</a>.</blockquote>
<div class="al-api"><b>void <a name="TRACE">TRACE</a>(char *msg, ...);</b></div><br>
Debugging helper macro. Normally compiles away to nothing, but if you
defined the preprocessor symbol DEBUGMODE before including Allegro headers,
it passes the supplied message given in ASCII format to al_trace().
Example:
<blockquote class="code"><pre>
#define DEBUGMODE
#include <allegro.h>
...
void my_blitter(<a href="alleg001.html#BITMAP" class="autotype" title="Stores the contents of a bitmap.">BITMAP</a> *source, int flags)
{
static int count_call = 0;
<a href="#TRACE" class="autotype" title="Debugging helper macro to trace messages.">TRACE</a>("my_blitter() called %d times.\n", count_call++);
...
}</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_trace" title="Outputs a debugging trace message.">al_trace</a>,
<a class="xref" href="#ASSERT" title="Debugging helper macro to assert.">ASSERT</a>,
<a class="xref" href="#register_trace_handler" title="Registers a custom handler for trace output.">register_trace_handler</a>.</blockquote>
<div class="al-api"><b>void <a name="register_assert_handler">register_assert_handler</a>(int (*handler)(const char *msg));</b></div><br>
Supplies a custom handler function for dealing with assert failures. Your
callback will be passed a formatted error message in ASCII, and should
return non-zero if it has processed the error, or zero to continue with
the default actions. You could use this to ignore assert failures, or to
display the error messages on a graphics mode screen without aborting the
program. You can call this function even when Allegro has not been
initialised. Example:
<blockquote class="code"><pre>
int show_but_continue(const char *text)
{
<a href="alleg035.html#alert" class="autotype" title="Displays a popup alert box.">alert</a>("Uh oh...", "Fasten your seat belts.", text,
"&Go on!", NULL, 'g', 0);
return 1;
}
...
register_assert(show_but_continue);
<a href="#ASSERT" class="autotype" title="Debugging helper macro to assert.">ASSERT</a>(0); /* This won't crash the program now. */</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_assert" title="Asserts at the specified file and line number.">al_assert</a>,
<a class="xref" href="#ASSERT" title="Debugging helper macro to assert.">ASSERT</a>,
<a class="xref" href="#register_trace_handler" title="Registers a custom handler for trace output.">register_trace_handler</a>.</blockquote>
<div class="al-api"><b>void <a name="register_trace_handler">register_trace_handler</a>(int (*handler)(const char *msg));</b></div><br>
Supplies a custom handler function for dealing with trace output. Your
callback will be passed a formatted error message in ASCII, and should
return non-zero if it has processed the message, or zero to continue with
the default actions. You could use this to ignore trace output, or to
display the messages on a second monochrome monitor, etc. You can call
this function even when Allegro has not been initialised. Example:
<blockquote class="code"><pre>
int network_broadcaster(const char *text)
{
int f;
for (int f = 0; f < connected_clients; f++)
send_msg_to_client(client[f], text);
return 0; /* Let normal tracing occur. */
}
...
<a href="#register_trace_handler" class="autotype" title="Registers a custom handler for trace output.">register_trace_handler</a>(network_broadcaster);
<a href="#TRACE" class="autotype" title="Debugging helper macro to trace messages.">TRACE</a>("Networked tracing activated\n");</pre></blockquote>
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#al_trace" title="Outputs a debugging trace message.">al_trace</a>,
<a class="xref" href="#TRACE" title="Debugging helper macro to trace messages.">TRACE</a>,
<a class="xref" href="#register_assert_handler" title="Registers a custom handler for assert failures.">register_assert_handler</a>.</blockquote>
<div class="al-api"><b>void <a name="al_assert">al_assert</a>(const char *file, int line);</b></div><br>
Raises an assert for an error at the specified file and line number. The
file parameter is always given in ASCII format. By default, this will call
the system driver's assert handler. If there is none, the error will be
sent to stderr and the program will abort. However, if the environment
variable ALLEGRO_ASSERT is set, this function writes a message into the
file specified by the environment variable and program execution will
continue. If none of this behaviours is wanted, you can override them with
a custom assert handler.
<p>
You will usually want to use the ASSERT() macro instead of calling this
function directly.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#ASSERT" title="Debugging helper macro to assert.">ASSERT</a>,
<a class="xref" href="#al_trace" title="Outputs a debugging trace message.">al_trace</a>,
<a class="xref" href="#register_assert_handler" title="Registers a custom handler for assert failures.">register_assert_handler</a>.</blockquote>
<div class="al-api"><b>void <a name="al_trace">al_trace</a>(const char *msg, ...);</b></div><br>
Outputs a debugging trace message, using a printf() format string given
in ASCII. If you have installed a custom trace handler it uses that, or
if the environment variable ALLEGRO_TRACE is set it writes into the file
specified by the environment, otherwise it writes the message to
"allegro.log" in the current directory. You will usually want to use the
TRACE() macro instead of calling this function directly.
<blockquote class="xref"><em><b>See also:</b></em>
<a class="xref" href="#TRACE" title="Debugging helper macro to trace messages.">TRACE</a>,
<a class="xref" href="#al_assert" title="Asserts at the specified file and line number.">al_assert</a>,
<a class="xref" href="#register_trace_handler" title="Registers a custom handler for trace output.">register_trace_handler</a>.</blockquote>
<hr><div class="al-back-to-contents"><a href="allegro.html">Back to contents</a></div>
</body>
</html>
