104 lines
2.2 KiB
Text
104 lines
2.2 KiB
Text
== Debug Logging
|
|
|
|
Declared in `<joey/debug.h>`.
|
|
|
|
A crash-tracing logger that writes to a file beside the executable. Debugging a
|
|
program on an emulated 1988 machine is awkward, and this is usually the fastest
|
|
way to find out what it did before it stopped doing it. The headless run
|
|
scripts retrieve the log automatically.
|
|
|
|
[NOTE]
|
|
====
|
|
The logger needs a multi-kilobyte ring buffer, which the tightest targets
|
|
cannot spare. Space Taxi compiles it out entirely on the IIgs and X68000 for
|
|
that reason. If you are debugging a memory-tight program, expect to do the
|
|
same and to observe hardware state through the emulator instead.
|
|
====
|
|
|
|
=== jlLog
|
|
|
|
[source,c]
|
|
----
|
|
void jlLog(const char *msg);
|
|
----
|
|
|
|
Appends a message to the log.
|
|
|
|
[cols="1,1,4", options="header"]
|
|
|===
|
|
|Parameter |Type |Description
|
|
|`msg` |`const char *` |NUL-terminated message.
|
|
|===
|
|
|
|
*Returns:* nothing.
|
|
|
|
=== jlLogF
|
|
|
|
[source,c]
|
|
----
|
|
void jlLogF(const char *fmt, ...);
|
|
----
|
|
|
|
Appends a formatted message, `printf` style, as one line: like `jlLog`, the
|
|
library ends the line, so the format needs no trailing `\n`.
|
|
|
|
[cols="1,1,4", options="header"]
|
|
|===
|
|
|Parameter |Type |Description
|
|
|`fmt` |`const char *` |Format string.
|
|
|`...` | |Arguments matching the format string.
|
|
|===
|
|
|
|
*Returns:* nothing.
|
|
|
|
[TIP]
|
|
====
|
|
Keep format strings simple. The C libraries on these targets vary in what they
|
|
support, and on the IIgs the `printf` family is expensive in both code size and
|
|
time.
|
|
====
|
|
|
|
=== jlLogFlush
|
|
|
|
[source,c]
|
|
----
|
|
void jlLogFlush(void);
|
|
----
|
|
|
|
Flushes buffered log output to disk. Call it before anything that might crash
|
|
or exit, or the last and most interesting lines may never be written.
|
|
|
|
*Parameters:* none. *Returns:* nothing.
|
|
|
|
=== jlLogReset
|
|
|
|
[source,c]
|
|
----
|
|
void jlLogReset(void);
|
|
----
|
|
|
|
Clears the log, discarding previous contents. Call once at startup so each run
|
|
produces a fresh log rather than appending to the last one.
|
|
|
|
*Parameters:* none. *Returns:* nothing.
|
|
|
|
[source,c]
|
|
----
|
|
int main(void) {
|
|
jlConfigT config;
|
|
|
|
config.codegenBytes = 32UL * 1024;
|
|
if (!jlInit(&config)) {
|
|
return 1;
|
|
}
|
|
|
|
jlLogReset();
|
|
jlLogF("build %s %s", __DATE__, __TIME__);
|
|
|
|
// ... game ...
|
|
|
|
jlLogFlush();
|
|
jlShutdown();
|
|
return 0;
|
|
}
|
|
----
|