How to install and use libcwd
-----------------------------

Tutorial on How to set up a project to use cmake, libcwd and aicxx git submodules (December 2022):
https://www.youtube.com/watch?v=uaJdQvt3oo4

Note to the developers
----------------------

The stability of libcwd depends on feedback I receive.
Because of the way libcwd works and is tested before releases,
it is very likely that libcwd either works OR core dumps
even before it reaches main.  If you are trying libcwd for
the first time and it doesn't work for you (even the simplest
application crashes) then please CONTACT ME!  It doesn't
mean that libcwd is a collection of bugs, it just means that
I do not have the same Operating System as you and I need
some help to make libcwd be able to reach main on your system.
I promise that from there on it will be as stable as a rock.
You can contact me through <carlo@alinoe.com>.

Introduction
------------

Libcwd is for use by developers while still developing: end
applications don't need it.  While still developing, you
will compile with -DCWDEBUG and link with -lcwd (and add its
install path to LD_LIBRARY_PATH).  A production version is then
simply compiled without -DCWDEBUG and not linked with -lcwd.

The library cannot be linked with static libraries (because
those are not compiled with -fPIC) therefore libtool drops
any inter-library dependency if you only have a static
library installed and will print something like:

 *** Warning: This library needs some functionality provided by -lXXX.
 *** I have the capability to make that library automatically link in when
 *** you link to this library.  But I can only do this if you have a
 *** shared version of the library, which you do not appear to have.

If this happens, then this means that you will need to
link your programs with -lcwd -lXXX, rather than just -lcwd.


Note that although a static library is provided (with the
configure option --enable-static), it is highly discouraged.
Most notably, you should only use libcwd.a as a result of
linking with "-static -lcwd"; dlopen(3) is not supported for
such statically linked applications.  If you want to use
dlopen(3) anyway together with libcwd then make sure that the
loaded module is not using libcwd and is not allocating any
memory. Otherwise it will not link or it will crash.


The directory `example-project' contains a fully functional
example project that uses autoconf, automake and libcwd.
Please read example-project/README for more info and a little
tutorial on the automake build environment.  For the example
project to work, you *first* need to install libcwd.

Please read the INSTALL file for a list of other needed
libraries and tools before attempting to compile libcwd.

The debug support can be divided into the following components:

1) Support for Object Oriented debug output (using ostream and
   debug objects for `channels' and `devices').
2) Support for memory allocation debugging.
3) General runtime debugging support (demangling, stack and call
   traces, break points (starting a gdb session from within the
   program), tracking and handling existing functions as objects,
   etc).

Detailed documentation and a tutorial can be found in the
directory doc/.