CC3Logging.h File Reference

Defines
#define	DEBUGGER()   { kill( getpid(), SIGINT ) ; }
#define	LOGGING_ENABLED   0
#define	LOGGING_INCLUDE_CODE_LOCATION   0
#define	LOGGING_LEVEL_TRACE   0

---

Detailed Description

---

Define Documentation

#define DEBUGGER

(

)

{ kill( getpid(), SIGINT ) ; }

Use this macro to open a break-point programmatically.

#define LOGGING_ENABLED   0

For Objective-C code, this library adds flexible, non-intrusive logging capabilities that can be efficiently enabled or disabled via compile switches.

There are four levels of logging: Trace, Info, Error and Debug, and each can be enabled independently via the LOGGING_LEVEL_TRACE, LOGGING_LEVEL_INFO, LOGGING_LEVEL_ERROR and LOGGING_LEVEL_DEBUG switches, respectively.

In addition, there are the following specialized logging switches that can be turned on to assist with diagnostics and troubleshooting:

LOGGING_REZLOAD - output log messages during 3D model resource loading

ALL logging can be enabled or disabled via the LOGGING_ENABLED switch.

Logging functions are implemented here via macros. Disabling logging, either entirely, or at a specific level, completely removes the corresponding log invocations from the compiled code, thus eliminating both the memory and CPU overhead that the logging calls would add. You might choose, for example, to completely remove all logging from production release code, by setting LOGGING_ENABLED off in your production builds settings. Or, as another example, you might choose to include Error logging in your production builds by turning only LOGGING_ENABLED and LOGGING_LEVEL_ERROR on, and turning the others off.

To perform logging, use any of the following function calls in your code:

LogCleanTrace(fmt, ...) - recommended for detailed tracing of program flow

• will print if LOGGING_LEVEL_TRACE is set on. LogTimedTrace(fmt, ...) - as above but prints a standard timestamp and app context preamble LogTrace(fmt, ...) - convenience alias for LogCleanTrace. Can be changed to LogTimedTrace below.

LogCleanInfo(fmt, ...) - recommended for general, infrequent, information messages

• will print if LOGGING_LEVEL_INFO is set on. LogTimedInfo(fmt, ...) - as above but prints a standard timestamp and app context preamble LogInfo(fmt, ...) - convenience alias for LogCleanInfo. Can be changed to LogTimedInfo below.

LogCleanError(fmt, ...) - recommended for use only when there is an error to be logged

• will print if LOGGING_LEVEL_ERROR is set on. LogTimedError(fmt, ...) - as above but prints a standard timestamp and app context preamble LogError(fmt, ...) - convenience alias for LogCleanError. Can be changed to LogTimedError below.

LogCleanDebug(fmt, ...) - recommended for temporary use during debugging

• will print if LOGGING_LEVEL_DEBUG is set on. LogTimedDebug(fmt, ...) - as above but prints a standard timestamp and app context preamble LogDebug(fmt, ...) - convenience alias for LogCleanDebug. Can be changed to LogTimedDebug below.

LogCleanRez(fmt, ...) - recommended for use during development

• will print if LOGGING_REZLOAD is set on. LogTimedRez(fmt, ...) - as above but prints a standard timestamp and app context preamble LogRez(fmt, ...) - convenience alias for LogCleanRez. Can be changed to LogTimedRez below.

In each case, the functions follow the general NSLog/printf template, where the first argument "fmt" is an NSString that optionally includes embedded Format Specifiers, and subsequent optional arguments indicate data to be formatted and inserted into the string. As with NSLog/printf, the number of optional arguments must match the number of embedded Format Specifiers. For more info, see the core documentation for NSLog and String Format Specifiers.

You can choose to have each logging entry automatically include class, method and line information by enabling the LOGGING_INCLUDE_CODE_LOCATION switch.

Although you can directly edit this file to turn on or off the switches below, the preferred technique is to set these switches via the compiler build setting GCC_PREPROCESSOR_DEFINITIONS in your build configuration. Set this switch to enable or disable logging capabilities. This can be set either here or via the compiler build setting GCC_PREPROCESSOR_DEFINITIONS in your build configuration. Using the compiler build setting is preferred for this to ensure that logging is not accidentally left enabled by accident in release builds.

#define LOGGING_INCLUDE_CODE_LOCATION   0

Set this switch to indicate whether or not to include class, method and line information in the log entries.

This can be set either here or as a compiler build setting.

#define LOGGING_LEVEL_TRACE   0

Set any or all of these switches to enable or disable logging at specific levels.

These can be set either here or as a compiler build settings.