== 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;
}
----