CnDebug Help

Welcome to use the log debugging tool "CnDebug/CnDebugViewer", which is developed by CnPack team. CnDebug is an interface unit running in Windows / x86 platform, provided to user to output the debug information. Now it only support Object Pascal (CnDebug.pas), can be used in Delphi and C++Builder.

Where to use CnDebug?

"Log message" debugging is widely used in our development, especially when breakpoint and step tracing are not applicable. Using MessageBox API to show some variable's value is a common way in "Log message" debugging. But such MessageBox showing is limited and will bring some side effects when the code is related to some re-painting message or complex user interface. We prefer a better way: logging debug message information in background and use other tools to show and analyze them.

Win32 platform provides an API OutputDebugString to log debugging message. If this API was called, the message string will be copied to an internal buffer of Windows. If the program was running under IDE, the message will be captured by Event Log window. If running alone and a Viewer exists, e.g. DebugView, the message will be captured by the Viewer. Otherwise, disappeared.

OutputDebugString is simple, but a little discommodious. One message only contains one string, which is not proper for viewer to distinguish the level or types, and can not be filtered. Comparing to OutputDebugString, CnDebug brings some enhancement to this mechanism, and implements a more powerful interface unit of debug message output for Delphi and C++Builder.

CnDebugger Introduction

CnDebug.pas has a global instance CnDebugger to control and send the debug message. CnDebugger provides a lot of methods to send not only simple string message, but also integer, float, color, RTTI information of objects and components. It can also install an exception handler to log the stack and other contents when exception occurred.

CnDebugger is created in initialization part of CnDebug.pas, and freed in finalization.

A Message from CnDebugger

For our viewer needs enough information to classify, filter the messages. So there must be more contents than a simple string in each message. A message contains below:

> - Msg: The text message, length limited.

> Level: An integer value for distinguish the message level. For example, if we set level = 2 in our filter. The messages whose level <= 2 can be recorded, those > 2 will be discarded. Now the level range is 0 to 3, Default filter is 3, which means record all. So Level can be used to control the message details.

> MsgType: Type of this message, e.g. Error or Warning.

> Tag: An additional tag for each message with limited length (Now is 8). Default is empty. It can be used for single filtering.

Above can all be controlled by user through various methods provided by CnDebugger.

Furthermore, some additional information is generated by CnDebugger internally. They can not be modified by user directly.

> - Indent: An integer value for viewer to collapse/expand messages in treeview. It's used in Enter or Leave methods of CnDebugger. Note: this information has relation ship with current thread.

> - Process ID: Current Process ID.

> - Thread ID: Current Thread ID.

Users can ignore them when calling sending methods.

How CnDebugger Compiled?

CnDebugger provides two kinds of output methods, Log and Trace. Both of them has similar parameters and function. The difference is: Log methods are only compiled when DEBUG defined when compiling, while Trace methods are compiled for all time, except NDEBUG defined. Here NDEBUG will overwrite DEBUG.

The expression of compiled is:

> - Log Compiled := IFNDEF NDEBUG and IFDEF DEBUG
> - Trace Compiled := IFNDEF NDEBUG

Log methods, which are only compiled when DEBUG defined, can be used to log some detailed messages in debugging. And Trace methods are compiled in normal situation. They can be used to log some key messages, even in public version of software. Also, you can build an NDEBUG version to disable both kinds of methods.

DEBUG or other conditions can be defined in Project Options dialog.

CnDebugger Exception Handler

CnDebugger can install an Exception handler for the application. When unhandled exception occurred, CnDebugger can record the stack information and the error line number (The application needs to be compiled with debug information). Here CnDebugger uses JCL library to capture the exception. To enable this function, you need to install JCL library and define USE_JCL condition. If no JCL library installed, you need to copy the files listed in the header of CnDebug.pas from JCL source package to your application to compile. "Include TD32 debug Info" or generating Map file option should be opened in compiling to obtain more information when exception raises.

CnDebugger Timing

CnDebugger provides StartTimeMark and StopTimeMark method for time measurement. It used x86 asm instructions to obtain the CPU period counter. You can write as below:

       // Start a new time counter, 1 means the counter id.
       StartTimeMark(1);
       // Do some other things

       // Stop the time counter.
       StopTimeMark(1);

At StopTimeMark called, CnDebugger will calculate the CPU period counters and send the result to viewer as a message. You can start more than one instance of timing counter, using different counter id.

CnDebugger's Performance

CnDebug can use different Channel to send the message out. Currently CnDebug uses share memory map queue as the channel. The share memory map queue should be created and maintained by CnDebugViewer. CnDebug's memory map channel will ignored all messages when no corresponding memory map was created. So if CnDebugViewer not started yet, CnDebug's output methods calling brings little performance effects to the host program.

If CnDebugViewer started and share memory map queue was created. All messages from CnDebug will be copied to this queue, and read out by CnDebugViewer. This memory coping way is better than SendMessage & WM_COPYDATA of uDbg/Overseer in performance aspect. Now CnWizards, the main product of CnPack Team, has already used CnDebug as its debug message output unit. It only brings a little effect to CnWizards' performance.

CnDebugger F.A.Q.

Method CnDebugger.EvaluateObject can show an Object's RTTI information in an Inspector-style form in runtime. This function needs condition SUPPORT_EVALUATE.

If your IDE does not support multi-byte character sets (MBCS), CnDebug.pas perhaps can not be compiled for its chinese characters in comments. This time you can use the "Comments Cropper" in CnWizards to delete the comments or only delete the extended ASCII characters and compile it again.

Any questions or suggestions, please contact us: master@cnpack.org. We'll try our best to help you.

Links

CnDebugViewer Help

CnPack IDE Wizards License

About CnPack

Copyrights 2001-2016 CnPack Team