Quick Reference

A one-page cheat sheet for the most common libcwd tasks.

Installation

• Read the INSTALL file.

See also: Configuration Options And Macros.

Using libcwd with a new project

• Add sys.h and debug.h as header files to root of your application. (An #include "sys.h" / #include "debug.h" must find them before any other include directory with those file names; the CMakeLists.txt of cwds takes care of that if you put them in the root).
• Also add the git submodule cwds in the root of your project by following the cwds setup instructions.
• Add #include "sys.h" to the top of every source file in your application.
• Add #include "debug.h" to every source file needing debug output/code.
• Dump the following at the start of your main() function:

/* Add this at the top of your main(). */
 
  Debug(NAMESPACE_DEBUG::init());
 
/* Add this at the start of each new thread. */
 
  Debug(NAMESPACE_DEBUG::init_thread());

• Linking with libcwd happens as dependency of the cwds submodule; just linking with ${AICXX_OBJECTS_LIST} also gets libcwd.

  target_link_libraries(my_executable PRIVATE ${AICXX_OBJECTS_LIST})

  If you are not using cwds for some reason then the cmake target for libcwd to link with is Libcwd::cwd, and you'll need a find_package(libcwd CONFIG) to make that target available.

Debug Output

• Add a .libcwdrc file to your HOME directory. For example,

silent = on
channels_default = off
 
# statefultask
#channels_on = warning,notice,system,statefultask,threadpool,evio,io,tls,demangler,bfd
#channels_on = action,semaphore,semaphorestats
 
# cwchessboard
#channels_on = warning,notice,system,widget,event,place,countboard,clipboard,parser,clip
 
gdb = /usr/bin/gdb -x $REPOBASE/.gdbinit $GDBCOMMANDFILE
xterm = konsole --name "attach_gdb" --hide-menubar --nofork --workdir "$PWD" --geometry 165x24-0-0 -e %s

Note how this turns all debug channels off by default. This allows you to set an environment variable, LIBCWD_RCFILE_OVERRIDE_NAME to point to a project/test specific file which then only has to bother itself with turning on channels. For example,

LIBCWD_RCFILE_OVERRIDE_NAME="$REPOROOT/libcwdrc_my_project"

that could contains just

# This is an override file; just define the debug channels that we need.
 
# libcwd default debug channels.
#channels_off = elfutils,demangler
channels_on = warning,debug,notice,system
 
# cwds
#channels_off = tracked,system,usage
channels_on = restart
 
# utils
#channels_off = semaphore,delayloop,tracker,semaphorestats
 
# threadpool
#channels_off = action,threadpool,threadpoolloop
 
# evio
#channels_off = evio,endofmsg,decoder,io

Now dc::notice is turned on by default, e.g.

Dout(dc::notice, "Hello" << ' ' << "World");
Dout(dc::notice|blank_label_cf|error_cf, "Hello World");

• Other Control flags.