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

 logSettings = ;
logSettings. = ;
logSettings.[0]. = ;
(&logSettings);

Example: Log all errors to the error console only

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

 logSettings = ;
logSettings. = ;
logSettings.[0]. = ;
(&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  level, const char *message) {
    // ...
}

 logSettings = ;
logSettings. = ;
logSettings.[0]. = ;
logSettings.[0].. = MyLogFunction;
(&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
(); // 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
("Debug-Values:\n");

// or

// Formatted output
("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.
(i >= 5);

// Will trigger an assertion when the "str" pointer is null.
(str != );

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