Tutorial 1: Hello World

Print your first line of debug output.

The smallest C++ program that prints «Hello World» as debug output to cerr is:

// This line should actually be part of a custom "debug.h" file.  See tutorial 2.
#include <libcwd/debug.h>
 
int main()
{
  Debug(NAMESPACE_DEBUG::init());
 
  // dc::notice can be turned on in the .libcwdrc file, but lets make sure it is here.
  Debug(if (!dc::notice.is_on()) dc::notice.on()); // Turn on the NOTICE Debug Channel.
 
  Dout(dc::notice, "Hello World");
}

Each of the lines of code in this first example program are explained below.

#include <libcwd/debug.h>

This header file contains all definitions and declarations that are needed for debug output. For example, it defines the macros Debug and Dout and declares the debug object libcw_do and the debug channel dc::notice.

FAQ

• What is defined *exactly* in `libcwd/debug.h`?

Debug(NAMESPACE_DEBUG::init());

This call checks that the libcwd header files that are being used belong to the libcwd.so shared object that the application linked with. It is also required before any debug info can be loaded of the respective loaded shared objects.

Debug(dc::notice.on());

This turns on the Debug Channel dc::notice. Without this line, the code Dout(dc::notice, "Hello World") would output nothing: all Debug Channels are off by default, at start up.

FAQ

• Why do I need to type the `Debug( )` around it?
• Which Debug Channels exist? Can I make my own?
• Can I turn Debug Channels off again? Can I do that recursively?
• Why do you call it a Debug *Channel*? What *is* a Debug Channel?

Debug(libcw_do.on());

This turns on the Debug Object libcw_do. Without this line, the code Dout(dc::notice, "Hello World") would output nothing: all Debug Objects are off by default, at start up.

A Debug Object is related to exactly one ostream. libcwd defines only one Debug Object by itself (being libcw_do), this is enough for most applications. The default ostream is cerr. Using the macro Dout causes debug output to be written to libcw_do.

FAQ

• Why do I need to type the `Debug( )` around it?
• Can I make my own Debug Object?
• Can I turn Debug Objects off again? Can I do that recursively?
• How do I set a new `ostream` for a given Debug Object?
• Why are Debug Objects turned off at creation?
• Why do you turn on the debug object after you enable a debug channel?
• Why do you call it a Debug *Object*? What *is* a Debug Object?

Dout(dc::notice, "Hello World");

This outputs "Hello World" to the ostream currently related to libcw_do provided that the Debug Channel dc::notice is turned on.

Output is written as if everything in the second field of the macro Dout is written to an ostream; it is "equivalent" with: cerr << "Hello World" << '\n';

FAQ

• Why is `Dout` a macro and not a template?
• Do I need to type that semi-colon after the macro? Why isn't it part of the macro?
• I made my own Debug Object, can I still use `Dout`?
• Is the second field of the macro still evaluated when the Debug Channel and/or Debug Object are turned off?
• Can I suppress that new-line character?

Continue with Tutorial 2: Creating Your Own Debug Channels.