Quick start
===========

./configure --prefix=/usr
make
su
make install

If that doesn't work, mail me: libcwd@alinoe.com
(include as many details as possible).

Building debian packages
========================

The released tar file contains a debian directory.
Untar the tar ball, cd into the source tree and build
the debian binary packages.

tar xzf libcwd-1.0.0.tar.gz
cd libcwd-1.0.0
fakeroot debian/rules binary

'fakeroot' is part of the fakeroot package, dh_testdir is part
of the debhelper package (sudo apt-get install fakeroot debhelper).
This results in two .deb files:

libcwd_1.0.0_ARCH.deb		: Libraries and headers.
libcwd-doc_1.0.0_all.deb	: Reference manual, tutorial and examples.

The package libcwd-doc installs the documentation in
file://usr/share/doc/libcwd-doc/documentation/index.html, which you
probably want to bookmark in your browser. And a tutorial in
file://usr/share/doc/libcwd-doc/documentation/tutorial/index.html.
An example is stored in /usr/share/doc/libcwd-doc/example-project.

Install both packages with:
sudo dpkg -i libcwd_1.0.0_ARCH.deb libcwd-doc_1.0.0_all.deb

Building RPMs
=============

The released tar file contains a .spec file.
Therefore you can build an rpm directly from the tar with

rpmbuild -ta libcwd-1.0.0.tar.gz

The resulting rpm will install two libraries:
libcwd.so and libcwd_r.so.  Be sure to link with -lcwd_r
if you want the thread-safe version!

I haven't tested this in years however, since I do
not longer use an rpm based distribution. Patches for
the spec file are welcome.

Needed tools
============

Check if you have all GNU tools/libraries/packages that libcwd depends on:

Primary site:
ftp://ftp.gnu.org/gnu/

List of mirrors:
http://www.gnu.org/order/ftp.html

Packages/versions needed
------------------------

i) The GNU compiler, version 3.4 or higher.
   Version 4.0 or higher is highly recommended.

    Location: gnu/gcc/
    Current version: 4.2.2

Alternatively you can install only
ia) gnu/gcc/gcc-core-<version>.tar.gz	and
ib) gnu/gcc/gcc-g++-<version>.tar.gz
 
Note: It is very unlikely that you want to install
the source tree of gcc/g++.  Please try to upgrade your
compiler the usual way if needed.
If you are using rpm's then you will need to
install/upgrade the following:
    gcc (3.3 or higher),
    gcc-c++ (of same version),
    libstdc++ (of same version) and
    cpp (of same version).
Check your installation on Fedora with:
    rpm -qa | egrep '^(gcc|libstdc|cpp)'

Note: If you don't use rpm's but are using tar balls,
then you do NOT need to download gnu/libstdc++/* because
gcc comes with libstdc++ included.
The gnu/libstdc++/ directory on GNU ftp sites are
for older compilers or to be used as source drop-in
when you compile g++ (replacing the normal stdc++ with
an alpha version).  You also don't need libg++.
Don't delete those libraries if you have them though
since existing binaries might need to link with them.

libcwd-1.0.0 was tested with gcc-3.3.6, gcc-3.4.0, gcc-3.4.1, gcc-3.4.6,
gcc-4.0.0, gcc-4.0.3, gcc-4.1.0, gcc-4.1.1, gcc-4.1.2,
gcc-4.2.0, gcc-4.2.1, gcc-4.2.2 and gcc version 4.3.0 20080121 (experimental).

The versions gcc-3.1.x and gcc-3.2.x might or might not work or
even compile. Especially gcc-3.1, gcc-3.1.1 and gcc-3.2 are
risky when used with threading; they might result in freeing a
pointer that is really a global struct when used with
a buggy NPTL (and libcwd will CORE when it detects that).
Other 3.[12].x versions should work but that is not garanteed.

Packages needed to run the testsuite
------------------------------------

ii) If you want to run the testsuite then you will have to install
dejagnu-1.4.2 or higher, which can be downloaded from ftp.gnu.org/gnu/dejagnu/,
or your local GNU mirror.

You will also need expect-5.32.2 (and tcl/tk 8.3.3?).  At least, expect 5.31.2
is known to hang.  You can get it from http://expect.nist.gov/.

Packages/versions needed as maintainer or when using SVN
--------------------------------------------------------

If you want to generate maintainer files (and you need that when you
get this package via svn; in that case you also need to configure using
--enable-maintainer-mode) then you also need to have the following tools:

iii)  GNU make
iv)   GNU m4
v)    cwautomacros  version 20080103 or later (from http://cwautomacros.berlios.de/)
vi)   autoconf	    version 2.57 or higher
vii)  automake	    version 1.7 or higher
viii) libtool	    version 1.4.2 or higher on linux, 1.5 or higher on other OS,
                    because libtool 1.4.x treats everything as C, causing the
		    constructors of global objects not to be called.

Each of those can be downloaded from your local GNU site.

Moreover, in order to generate the documentation, you need to
have the following installed:

ix)   doxygen	    version 1.3.6 or higher (http://www.doxygen.org/)
x)    graphviz	    http://www.research.att.com/sw/tools/graphviz/


Hackers info
============

-=i=-

'configure' has a few interesting options.  You can list them by issuing:

./configure --help

There is no reason to use libcwd's feature options (--disable-alloc,
--disable-magic, --disable-marker and --disable-location).
Actually, I forgot why they are there :).  You can read more about the
configuration options and what they do in include/libcwd/config.h.

If you want to change Makefile.am files and the like then you'll need to
use --enable-maintainer-mode.  If you enable maintainer-mode then you
will need GNU make, other make won't work (you also need a LOT of other
extra tools installed on your system, only for the brave thus).

-=ii=-

The configure script looks for a GNU C++ compiler version 3.0 or higher.
If it can't find one (it will only find one when there is a g++ or c++ in
your PATH), then you can specify the right path during configuration.
For example, I configure libcwd as follows to compile with the latest SVN
version of g++, which I installed in /usr/local/bin/g++-svn (and
/usr/local/bin is in my PATH):

CC="gcc-svn" CXX="g++-svn" ./configure

-=iii=-

If you don't have an ELF32 system and therefore need to link with libbfd, then you
can configure using --enable-libbfd.  If libiberty.a or libbfd.so are in an
unusual directory, then you will have to set LDFLAGS prior to running ./configure:

LDFLAGS="-L/usr/gnu/lib" CPPFLAGS="-I/usr/gnu/include" ./configure

-=iv=-

You can install libcwd in a 'staging' directory by issuing

make DESTDIR=/tmp/staging install

this can come in handy when you want to build an rpm for instance.

-=v=-

The Makefile has the following targets:

make [all-recursive]
make install
make uninstall
make clean
make distclean

If you configured with --enable-maintainer-mode then the following
targets exist as well:

make dist					// Create tar ball
make svn-clean					// Erase everything that was generated somehow
make check					// Run test suite
make tar					// Create tar ball
make rpm					// Create rpms
make ChangeLog					// Generate ChangeLog from SVN database
make full-check					// Iterate over all configurations and all compiler versions

It is not garanteed that these work on another machine than mine however.

-=vi=-

Finally, you can also build libcwd in a different directory than the source
tree is in:

tar xzf libcwd-1.0.0.tar.gz
mkdir libcwd-objdir
cd libcwd-objdir
../libcwd-1.0.0/configure --prefix=/usr
make
su
make install

that way your source tree stays completely distclean :)
