CUnit : A Unit Testing Framework
			  http://cunit.sourceforge.net

CUnit is a Unit testing framework for C.

The basic framework is platform/version independent and should be
portable to all platforms.  CUnit provides various interfaces to
the framework, some of which are platform dependent (e.g. curses on
*nix).  Building other interfaces should be straightforward with
the facilities provided in the framework.

CUnit is built as either a static or shared library which provides 
framework support when linked into user testing code.  The framework 
complies with the conventional structure of test cases bundled into 
suites which are registered with the framework for running.  See the
documentation for more about the structure and use of the framework.

Note - the windows-specific gui interface is not yet written.  It is
still necessary to use either the automated, basic, or console
interfaces to CUnit on Windows at this time.

-------------------------------------------------------
Important Note - Changes to CUnit Structure & Interface
-------------------------------------------------------

As of version 2.0, the interface functions used to interact with the
CUnit framework have changed.  The original interface did not attempt
to protect user code from name clashes with public CUnit functions and
variables.  To minimize such name clashes, all CUnit public functions
are now prefixed with 'CU_'.

The old public names are deprecated as of Version 2.0, but continue
to be supported with conversion macros.  In order to compile older code
using the original interface, it is now necessary to compile with the
macro -USE_DEPRECATED_CUNIT_NAMES defined.  If there are any problems
compiling older code, please file a bug report.

In addition, the DTD and XSL files for output from the automated test
interface have been updated to support both old and new file structure.
That is, a List or Run file generated using the version 1.1 library
should be (1) valid under the version 2 DTD's and (2) formatted
correctly by the version 2 XSL's.  Note, however, that this has not
been extended to the Memory-Dump DTD and XSL files.  That is, memory
dumps created using version 1.1 are ill-formed and incorrectly
formatted using the version 2 DTD and XSL files.

Another exception to backward compatibility occurs if the user has
directly manipulated the global variables in version 1.1.  The
original CUnit structure included global variables error_number and
g_pTestRegistry which have been removed from the global namespace as
of Version 2.0.  Any user code which directly accessed these variables
will break.  The variables must be retrieved using the accessor
functions CU__get_error() and CU_get_registry().

Similarly, user code retrieving the active test registry and directly
manipulating the uiNumberOfFailures or pResult members will break.
These members have been moved to the TestRun.c part of the framework
and are no longer available in the test registry as of version 2.0.

Another change in Version 2.0 is the update of the framework terminology.
What were termed 'test groups' in the original structure are now called
"suites", and "test cases" are now just "tests".  This change was made to
bring CUnit in conformance with standard testing terminology, and results
in a change in the name of some functions (e.g. run_group_tests() is
now CU_run_suite().

---------------------------------------
Building the CUnit Library and Examples
---------------------------------------

All Platforms:

  As of Version 2.0, a set of Jamfiles is provided for cross-platform
  building of the library, examples, and tests.  The jam build system was
  implemented using ftjam 2.3.2 (http://www.freetype.org/jam/index.html).
  It may work under the original Perforce jam implementation, but has not
  been tested.  It has been tested under gcc on Linux, and Borland C++ 5.5, 
  VC7, MinGW 3.2.3, and Open Watcom 1.3 on Windows.  Due to the nature of 
  jam, the build system should be readily extensible to other platforms.

  The jam file set supports both standard and custom symbolic build
  targets (install, uninstall, clean, libcunit, examples, test).  A
  customized Jambase file is provided which sorts out some of the
  rough edges for MinGW and Watcom on Windows.  It may not be necessary
  when using gcc, Borland, or VC, but it won't hurt either.
  
  The files generated during the build are placed in a subdirectory
  given by <CONFIG>/<PLATFORM>, where:
  
    <CONFIG> = Debug or Release
    <PLATFORM> = bcc, mingw, msvc, watcom, linux
    
  This allows easy switching between compilers without overlap of the output 
  files.  The <CONFIG> is determined by whether NODEBUG is defined in your
  Jamrules file.  <PLATFORM> is set automatically in Jamrules.

  To build using jam:

    1. Set the working directory to the top of the source tree
    
    2. Generate Jamrules
       a. On Linux, run autoconf & configure
       b. On Windows, copy Jamrules.in to Jamrules

    3. Edit the top section of Jamrules to match your preferences

    4. jam -f Jambase install

Linux:

  In addition to jam, the standard GNU build system is still supported.
  The usual sequence of steps should succeed in building and installing CUnit:
    1. aclocal  (if necessary)
    2. autoconf (if necessary)
    3. automake (if necessary)
    4. chmod u+x configure (if necessary)
    5. ./configure --prefix <Your choice of directory for installation>
    6. make
    7. make install

  What's installed:
    1. libcunit.a (Library file)
    2. CUnit Header files
    3. DTD and XSL files supporting xml output files in share directory
    4. Man Pages in relevant man directories under the installation path.
    5. HTML users guide in the doc subdirectory of the installation path.
    6. Example & test programs in the share subdirectory of the install path.

Windows:

  Jam is the preferred build system for Windows.  A set of old VC6 project
  files is included which have been partially updated but not tested.  If
  they don't work and you get them working, we'd be happy to include them
  in the CUnit distribution.  A set of Visual Studio 2003/VC7 solution and
  project files has also been provided in the VC7 subdirectory.  Similarly,
  a set of Visual Studio 2005/VC8 solution and project files is located in
  the VC8 subdirectory.  The latter should work with all versions of VC 2005,
  including the Express edition.