Final Platform Layer  0.9.6-beta
Debug & Logging

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, a mode in which you can define one writer for every log level and one mode in which you have a writer for each log-level separately. By default, it uses the first mode, which is 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

Example: Log all errors to the error console only

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

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) {
// ...
}
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 an 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 a assertion that will crash your application immediately.
fplAssert(i >= 5);
// Will trigger a assertion when the "str" pointer is null.
Warning
When you are building in release-mode runtime-time assertions are compiled out entirely - unless you have specific 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 specific 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 to never define this in your code, but rather outside in your build-configuration.
fplDebugBreak
#define fplDebugBreak()
Stops the debugger on this line always.
Definition: final_platform_layer.h:2126
fplLogLevel
fplLogLevel
An enumeration of log levels.
Definition: final_platform_layer.h:4025
fplDebugOut
fpl_platform_api void fplDebugOut(const char *text)
Writes the given text into the debugger output stream.
fplLogSettings::maxLevel
fplLogLevel maxLevel
Maximum log level.
Definition: final_platform_layer.h:4124
fplLogWriterFlags_ErrorConsole
Error-Console output.
Definition: final_platform_layer.h:4067
fplDebugFormatOut
fpl_common_api void fplDebugFormatOut(const char *format,...)
Writes the given formatted text into the debugger output stream.
fplLogWriter::flags
fplLogWriterFlags flags
Flags.
Definition: final_platform_layer.h:4091
fplLogSettings::writers
fplLogWriter writers[1]
Single writer.
Definition: final_platform_layer.h:4121
fplLogLevel_All
All.
Definition: final_platform_layer.h:4027
fplLogWriter::custom
fplLogWriterCustom custom
Custom.
Definition: final_platform_layer.h:4095
fplAssert
#define fplAssert(exp)
Breaks with an runtime assertion, when the specified expression evaluates to false.
Definition: final_platform_layer.h:2081
fplLogWriterFlags_StandardConsole
Standard-Console output.
Definition: final_platform_layer.h:4065
fplSetLogSettings
fpl_common_api void fplSetLogSettings(const fplLogSettings *params)
Overwrites the current log settings.
fplZeroInit
#define fplZeroInit
Initializes a struct to zero.
Definition: final_platform_layer.h:2208
fplStaticAssert
#define fplStaticAssert(exp)
Breaks the compilation, when the specified expression evaluates to false.
Definition: final_platform_layer.h:2083
fpl_null
#define fpl_null
Null.
Definition: final_platform_layer.h:2166
fplLogWriterCustom::callback
fpl_log_func_callback * callback
User callback.
Definition: final_platform_layer.h:4085
fplLogSettings
A structure containing log settings.
Definition: final_platform_layer.h:4099
fplLogWriterFlags_Custom
Custom output.
Definition: final_platform_layer.h:4071
fplLogLevel_Error
Error.
Definition: final_platform_layer.h:4031