Debug & Logging

Table of Contents

• Logging
  • Example: Log everything to the standard console only
  • Example: Log all errors to the error console only
  • Example: Log all errors to a custom logging function
• Debug
  • Forced Breakpoint
  • Output to the Debug-Console
• Assertions
  • Runtime assertion
  • Compile-time / static assertion
  • Enable/Disable assertions

Logging

FPL has an internal logging system built-in.
By default this logging system is disabled, but you can enable it by defining the preprocessor definition FPL_LOGGING before including the FPL header file.

You can change the maximum log-level using fplSetMaxLogLevel() . By default, this is set to fplLogLevel_Critical which means that only system-wide critical errors will be reported.
When the logging system is enabled, you can get or change the configuration using fplGetLogSettings() / fplSetLogSettings() respectively.

This configuration has two modes: one shared writer used for every log level, or a separate writer for each log level. By default, it uses the first mode - one writer for all log levels.
To change this behavior, you can set the preprocessor definition FPL_LOG_MULTIPLE_WRITERS. With this, you can change the logging in every detail.

A log writer can be configured to log to multiple logging-targets.

FPL supports up to 4 log targets:

• Console standard output
• Console error output
• Debug console output
• Custom callback

See fplLogWriterFlags and fplLogSettings for more details.

Example: Log everything to the standard console only

fplLogSettings logSettings = fplZeroInit;
logSettings.maxLevel = fplLogLevel_All;
logSettings.writers[0].flags = fplLogWriterFlags_StandardConsole;
fplSetLogSettings(&logSettings);

Example: Log all errors to the error console only

Log all errors, warnings, and criticals to the default error console.

fplLogSettings logSettings = fplZeroInit;
logSettings.maxLevel = fplLogLevel_Error;
logSettings.writers[0].flags = fplLogWriterFlags_ErrorConsole;
fplSetLogSettings(&logSettings);

Example: Log all errors to a custom logging function

Log all errors, warnings, and criticals to a custom callback defined as fpl_log_func_callback .

static void MyLogFunction(const fplLogLevel level, const char *message) {
    // ...
}
 
fplLogSettings logSettings = fplZeroInit;
logSettings.maxLevel = fplLogLevel_Error;
logSettings.writers[0].flags = fplLogWriterFlags_Custom;
logSettings.writers[0].custom.callback = MyLogFunction;
fplSetLogSettings(&logSettings);

Debug

Forced Breakpoint

You can force to stop on a specific line of code always by calling the function fplDebugBreak() .
It works exactly like a breakpoint, but it will always break until you remove the call to it.

Example:

// ... code
fplDebugBreak(); // Debugger will always stop here
// ... code

Output to the Debug-Console

On IDE's such as visual studio you can use fplDebugOut() or fplDebugFormatOut() to print out stuff in the console directly in your IDE.

Example:

// Basic output
fplDebugOut("Debug-Values:\n");
 
// or
 
// Formatted output
fplDebugFormatOut("Value of X: %f\n", xValue);

Assertions

FPL contains runtime and compile-time assertion macros, which you can use to ensure application state consistency.

Runtime assertion

You can use the macro function fplAssert() to trigger a runtime assertion in a debug-build.
When the condition in your assertion is false, your application will crash immediately.

Example:

// When i is less than 5 this code will trigger an assertion that will crash your application immediately.
fplAssert(i >= 5);
 
// Will trigger an assertion when the "str" pointer is null.
fplAssert(str != fpl_null);

Warning

When you are building in release-mode, runtime assertions are compiled out entirely - unless you have specified FPL_FORCE_ASSERTIONS!

Do not call any important functions inside an assertion statement, because it will get compiled out eventually.

Compile-time / static assertion

You can use the macro function fplStaticAssert() to trigger a compile-time assertion in a debug-build.

Example:

typedef struct myStruct {
  int a;
  float b;
} myStruct;
 
// Will throw a compile error when "myStruct" is not of total size of 8-bytes
fplStaticAssert(sizeof(myStruct) == 8);

Warning

When you are building in release-mode, compile-time assertions are compiled out entirely - unless you have specified FPL_FORCE_ASSERTIONS!

Do not call any important functions inside an assertion statement, because it will get compiled out eventually.

Enable/Disable assertions

In Debug-Mode assertions are enabled, unless you have specified FPL_NO_ASSERTIONS.
In Release-Mode assertions are disabled, unless you have specified FPL_FORCE_ASSERTIONS.

You can use FPL_DEBUG or FPL_RELEASE to force either a "Release" or "Debug" mode.
See Compiler Options for more details.

Note

I highly recommend never defining this in your code, but rather outside in your build-configuration.