debug_basics - ryzom/ryzomcore GitHub Wiki

In addition to the logging facilities NeL provides some basic debugging tools and the basis of some exception handling. There are two main debugging macros and one exception that are useful in every day development: nlstop, nlerror() and the EFatalError exception. You can also find an informative sample called debug in the NeL source tree that covers this subject as well as some basic logging.

The nlstop macro is the most basic of the two. It requires no parameters and simply stops the code at that point. The nlstop macro perform no login in non-Debug build modes but it is important to be familiar with it and use it when building in Debug modes such as Debug or ReleaseDebug. In the Microsoft IDEs the macro will opt to set a breakpoint in the code and exit you if you are running within the IDE. This is a great way to programmatically set breakpoints for failure code rather than a simple error. The nlstop macro does throw the EFatalException exception, but unlike nlerror() (which will be covered next) it does not allow you to provide any contextual information.

The nlerror() macro is a useful variation in that you can use it immediately halt execution of the program but still provide useful, context sensitive logging. Because nlerror() calls abort() it should be used sparingly and only in situations where continued execution of code could cause problems, predictable crashes and other things of that nature. An important feature of nlerror() is that it emits an EFatalException exception that you can catch. This is tremendously useful for any cleanup that may be necessary upon a fatal error. Here's an example:

// when the program failed, call nlerror(), it displays the message and throws a EFatalError to
// exit the program. don't forget to put a try/catch block everywhere an nlerror could
// occurs. (In Visual Studio press F5 to continue)
try
{
	nlerror("nlerror() %d", 4);
}
catch(EFatalError &)
{
	// just continue...
	nlinfo("nlerror() generated an EFatalError exception, clean up and continue.");
}

Source