This is version 2.0.0 of CCCC a C and C++ Code Counter
======================================================

COMPILING
---------

The distribution includes the following files
cccc.g          a grammar data file in PCCTS format to give a rough C++ parser
cccc*.cc        C++ source files to implement the analyser
cccc*.h              ""                       ""
*.cpp        }  C++ files generated by PCCTS to implement a parser for the
other *.h    }  language specified in cccc.g
makefile        I hope you know what this is for...
cccc_tmt.dat    configuration file for display of different metrics
cccc_inf.dat }  HTML scripts for the help text included in the generated
cccc_met.dat }  reports

The make variable CONF is used to select one of a number of configuration
sets for different environments - expect to have to edit the location of
the PCCTS files if they are not in the location shown.  If the make variable
PBIN is not defined, the makefile rule to convert the .g file into the
various .cpp and .h files it makes will be suppressed.  A set of these 
generated files is included in the distribution, so if you don't have PCCTS
compiled, you can still build and link CCCC from these distributed files
(obviously changing the cccc.g file will have little effect, and I really
don't recommend changing the generated files).  In any case you will need 
to install the PCCTS source code and make the makefile reflect its location
as the generated files require a number of support files which are found 
in the $(PCCTS)/h directory.


INSTALLING
----------

The make target 'install' copies the binaries and the required .dat files 
to the library and binary locations selected for the platform specified. 
On Unix, the .dat files will be stored in /usr/local/lib/cccc, while the 
binary will go in /usr/local/bin.  On DOS, both .dat files and binary 
will go in c:\cccc.  You are welcome to change these locations, but the 
library location should probably agree with the directory specified in 
cccc.h.

If you wish to customize the .dat files (either to make them reflect your own
standards or to alter the trailing help text), you may have multiple copies in
different directories and select among the directories using the -l flag 
described below.  If the treatment configuration file cannot be found, there 
will be no highlighting of high values.

RUNNING
-------
The simplest thing to do is to run

        cccc *.cc *.h 

on the command line.  

When the program runs it should generate progress messages and parse error 
messages on standard error.

The HTML report on metrics is generated in the file cccc.htm, unless you
specify another file using the -o option.  The HTML report can be 
viewed with a standard HTML browser with reasonable table support.  I will 
try to improve the standard of presentation for Lynx users, but for the moment
Netscape and IE are recommended.  Version 3 of Netscape is preferable to
version 2 because it supports specification of a background colour for
cells in a table, giving a much stronger visual cue on metric values which
lie outside the configurable preferred ranges (under version 2 the font is
italic or bold).   I haven't checked Arena or Mosaic lately, but with a bit
of luck they should work reasonable.

The utility supports a range of flags, of which the most useful are:
  -l   which takes an argument for the directory which is searched for 
       the *.dat files; and
  -f   which is used to introduce a file which contains a list of files to
       process instead of requiring the files to be listed on the command line.
For more details of command line options please read the source code of
ccccmain.cc.

In general, please read the source files to see how things work, and change 
anything you like.


Revision history

version 2.0.0 
released 22 February 1997
Initial public version.
Both Linux and DOS/Win versions compile cleanly and successfully process
cccc's own code.  The DOS/Win version has been known to cause reboots on exit
when processing larger projects (20KLOC+)

version 2.0.1
released 28 February 1997
Implemented a strategy of using token consumption rather than parser 
recognition of balanced constructs for brace_block.  This avoids extreme stack
extension (i.e. 1 level of recursion in the recognition function for 
balanced_list per token in a function body).  This is suspected of causing the
DOS/Win version reboot problem, which has gone away on initial testing of this
version.  Also speeds up recognition (the 20KLOC project now processed on 
Linux in 2.5 mins vs 8mins before).
Rehashed the high level structural metric to generate modified forms of the 
Henry-Kafura information flow metrics instead of using the Card & Glass 
formulation.

version 2.02
released 3 March 1997
HTML report now generated as a single file: command line options allow for
selective generation of only the tables required.
Tidied up and checked command line options and the usage message in general.
Added decent table of contents, harmonised section names.
Added cross links from summary to detail tables and back.
Made visibility public if no explicit visibility known.

version 2.03
released 6 March 1997
Included time.h in cccc_htm.h (leaving this out caused a compile error under 
DJGPP but not under Linux).  
Fiddled with the CONVERT_STRSTREAM() macro in cccc.h (a proposed fix for 
failing to compile under OSF, not yet tested).
Made generation of the extent datafiles and the database dump dependent on
debug flags.
Changed message about location of HTML report to reflect -o option.

version 2.04
released 12 March 1997
Incorporated fixes to improve the chances that the program now compiles 
and runs correctly under non GNU compilers.  
GNU C++ and DEC C++ can both be made to work, but the communication between
the analyser front end and database must be done with different classes from
the strstream hierarchy in either case.  cccc.h defines macros which ensure
that an appropriate implementation gets used on each platform.
Also fixed a few incorrect casts from CCCC_Html_Ofstream to ostream& which GNU 
C++ tolerated fine but caused a crash under DEC C++.  CCCC_Html_Ofstream 
used to inherit from ofstream, but doesn't any more, so the cast was
definitely wrong - I think the reason it was tolerated was because the
first data member defined in the class was the ofstream object used to 
do the actual output, so when the containing object was cast to an ostream
the address of the outer object was interpreted as an ostream, and there just
happened to be a valid ostream object sitting at that address.


