This is a little example project using autoconf and automake.

IMPORTANT: This example project only works of you already
           compiled and *installed* libcwd!

What and How
------------

This example shows how to use libcwd in your application project.
It doesn't show how to use libcwd for a library project, please
read the reference manual for that.

You can add new debug channels by adding them to debug.cc
and debug.h.  The example is ready-to-use, you only need
to edit the name of the namespace that the channels are
put into (again, in debug.cc and debug.h).  You are free to
choose whatever you like for "::myproject::debug::channels"
except "::" (or "").  Of course, you are highly advised to
use a namespace that minimizes the chance of a collision
with future libraries that you might want to link with
who might also use libcwd.

Please read the following and type the given commands (marked
with a '*') in order to learn and understand the concept of
this build environment.

Tutorial
--------

A project source knows four states:

- "maintainer clean"
- "dist clean"
- "clean" (configured)
- "built" (compiled).

"maintainer clean" means that ALL files that can be
  generated somehow are removed.  The remaining files
  are files that are actually human written and generally
  part of the version control repository.

"dist clean" means that the source tree contains all files
  that are distributed (put in the tar ball that is released).
  This often includes all generated files that are not
  dependent on the target machine somehow (and thus CAN be
  generated by the maintainer) and for which special tools
  might be necessary that not everyone has installed (such
  as aclocal, autoheader, autoconf and automake).

"clean" means that all files are generated, including
  those that are dependent on the target machine.  Most
  notably the cache file with test results is still
  around so that a reconfiguration is much faster (but
  doesn't really re-test anything *)).  All object files
  and executables are removed however.

  *) Recent versions of autoconf have changed this
  default behaviour.  The default is to have no cache
  anymore: it was doing more bad than good because it would
  not properly detect changes in the environment (or changes
  in the compiler version) between runs.

"built" means that the package has been compiled.
  It is ready for a 'make install'.


The "clean" and "built" states contain a `Makefile'
with clean targets to clean the source tree to any of
these states:

  make clean
  make distclean
  make maintainer-clean

Of course these targets are not available when the
source tree is "distclean" because then no Makefiles
exist.  Therefore you cannot go directly from
"dist clean" to "maintainer clean".


Whenever you invoke `make', it first looks for a file
`makefile' (only when it does not exist it will
look for a file `Makefile', note the uppercase 'M').
I used that fact to allow you, the maintainer, to use
`make' in a "maintainer clean" source tree to generate
a "clean" source tree: The `makefile' tries to
include a `Makefile' but when it does not succeed then
the first target will be `maintainer-startup'; hence a
`make' in a "maintainer clean" source tree is equivalent
to a `make maintainer-startup'.

* Type "make" to go from

	"maintainer clean"  -->  "clean"

It goes straight to "clean" instead of "dist clean",
because normally you will always ./configure the source
tree the same way anyway.  Most notably, you will
always use --enable-maintainer-mode for ./configure
in order to enable the maintainer targets (maintainer-clean
is one of those targets).

Have a look at `makefile' to see what you just did.

Note that many projects do not use this method.  Instead
they use a script (usually called 'autogen.sh') that has
to be run to go from "maintainer clean" to "dist clean"
and then one has to manually run ./configure after that.

* Next type: "make" again to go from

	"clean"  -->  "built"

* You can now type "./program" to run and test the
generated program.

The source tree was configured with --enable-debugging.
Lets reconfigure it, without debugging:

* Type:

	make distclean

Now the source tree is in the state as the users of your product
will receive it.  You can try to configure it in the same way as
they do, by typing just ./configure, but then you will be cripled
a bit because certain targets won't exist.

* So instead do:

	./configure --enable-maintainer-mode

* Then rebuild the source tree:

	make

Now the program has been built without debugging support.
It did not link with libcwd, nor does libcwd need to be installed.


We have three different types of makefiles:

1) makefile		: The makefile for the master himself in order to
			  escape from a "maintainer clean" source tree and
			  generate a "clean" source tree from it.  This
			  makefile is not distributed.

2) maintMakefile.in	: A makefile with rules for "the maintainer",
			  meaning that it contains rules to generate
			  files that are not dependent on the target host.
			  Usually special tools are needed to generate these
			  files which is why "the maintainer" is generating
			  them and the result is put in the distribution.
			  The rules to build these files are only enabled
			  when the package is configured with
			  --enable-maintainer-mode.
			  Note that also Makefile.{am|in} can contain
			  maintainer specific rules.

3) Makefile.am		: The makefile that describes how to build the
			  application.

Other makefiles are generated:

The "dist clean" state will contain a "Makefile.in" which was generated
from "Makefile.am" by automake.  And the "clean" state will additionally
contain the "Makefile" that was generated from "Makefile.in" by running
"configure", the latter also generates a "maintMakefile" from
"maintMakefile.in".


Finally, let us generate a distribution:

	./configure --enable-maintainer-mode
	make dist

This generated a "dist clean" source tree which was tarred up.
You can see what is inside the tar with: tar tzf project-0.0.1.tar.gz

Lets unpack and build it like ordinairy users will do:

tar xzf project-0.0.1.tar.gz
cd project-0.0.1
./configure
make


PS If you see a file 'debug.h.maintainer' then you probably checked
   out this directory from the libcwd SVN repository.  That file
   is not supposed to be a part of your project, just remove it.
   Before removing it however, make sure you have a file called
   debug.h in the current directory.  If not, generate it from
   debug.h.maintainer by going one directory down - configure
   libcwd with --enable-maintainer-mode (which you should always
   do when using SVN) and running: make example-project/debug.h

