libcwd

libcwd copied to clipboard

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 [email protected].

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