Programming Reference:Debug Output

From BCI2000 Wiki
Revision as of 16:21, 3 April 2007 by Mellinger (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

When writing your own BCI2000 module, you will sometimes want to report values of variables, execution of a certain function, or other information that is

  • irrelevant to the user, but
  • helps you check whether your code does what it is supposed to.

Often, programmers use individual log files for debugging output, and review those files while their program runs, or afterwards.

This page describes how the BCI2000 C++ framework allows you to easily display debugging information in the operator module's log window, without bothering about creating your own log file. Nevertheless, you are free to use your own log file if you feel that this better fits your needs.

Debugging Stream bcidbg

Similar to the bcierr and bciout streams used for error handling and user warnings, BCI2000 provides a std::ostream derived object that accepts strings and numbers for formatted output. Like the output of bcierr and bciout, data from bcidbg is directed into the operator module's log window. Similar to error and warning messages, debugging messages will be time stamped and provided with a function context.

However, there are important differences:

  • Unlike for bcierr, the framework does not interpret the fact that something was written to the stream.
  • bcidbg can conditionally ignore the data inserted into it, according to a user-defined global setting. That way, you need not remove your debugging code, nor devise your own conditional output scheme.
  • Messages are formatted unobtrusively, and will not automatically pop up the window.

The bcidbg stream is available globally, and used as any other std::ostream descendant:

mSomeDataMember = SomeFunction();
bcidbg << "Set mSomeDataMember to " << mSomeDataMember << endl;

Note that, just as for bcierr and bciout, writing to bcidbg will not take effect unless it is flushed by inserting flush or endl. (The latter will insert a newline character before flushing the stream.)

The Debug Level

A Debug Level concept is used to control the output of debug messages. Basically, a user-specified debug level is compared against individual messages' debug levels, and messages with a debug level above the user-specified debug level will be suppressed from the output. As the debug level defaults to 0, no debug messages will be visible to an end user unless configured accordingly.

Individual messages are associated with a numerical value, their Debug Level, roughly correlating with their significance. Important and sparse messages are given a low debug level value, less important and probably more frequent messages are given a higher debug level.

Message Debug Level

The default message debug level is 1.

bcidbg << "This is an important message on any level of debugging" << endl;

To give a message a higher debug level, put it in brackets after the bcidbg name:

bcidbg( 10 ) << "This is a fairly uninteresting message" << endl;

Although there is practically no upper limit to debug level values, a usual range for debug levels is from 1 to 10.

Global Debug Level

The amount of actual debugging output is governed by a global debug level. In BCI2000, this value is corresponds to the DebugLevel parameter. This parameter is not normally available, and must be specified from the command line when starting a module:

FeedbackDemo --DebugLevel=10

will start the FeedbackDemo module with a quite verbose debug level of 10. Note that the debug level parameter will propagate to the other modules only after "Set Config" has been pressed from the operator module. Thus, other modules must be started with the DebugLevel argument as well if you need to view debugging messages from operation phases prior to the Initialization Phase.

See also: Error Streams|States of Operation