Tutorial 1: Hello World

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

[download]

Compile as: g++ -g -DCWDEBUG hello_world.cc -lcwd -o hello_world

// These four lines should actually be part of a custom "sys.h" file.  See tutorial 2.
#ifndef _GNU_SOURCE                     // Already defined by g++ 3.0 and higher.
#define _GNU_SOURCE                     // This must be defined before including <libcwd/sys.h>
#endif
#include <libcwd/sys.h>                 // This must be the first header file
// This line should actually be part of a custom "debug.h" file.  See tutorial 2.
#include <libcwd/debug.h>

int main(void)
{
  Debug( dc::notice.on() );             // Turn on the NOTICE Debug Channel.
  Debug( libcw_do.on() );               // Turn on the default Debug Object.

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

  return 0;
}

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

#define _GNU_SOURCE

This define is necessary to tell the system headers that you want to use the GNU extensions (see /usr/include/features.h).  In order to make you explicitely aware of the fact that it is defined, libcwd does not define this macro itself (which it could do inside <libcwd/sys.h>), but forces you to define it when using libcwd.  Note that you only really have to define it when you compiled libcwd with threading support.  If you do not define this macro and libcwd needs it, then you will get a compile error in <libcwd/sys.h> telling you so.

#include <libcwd/sys.h>

This must be the very first header file that is included; even before system header files.  Every source file that includes other libcwd headers must include it.

#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.

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.

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.

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';