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 reasonably well.

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.

version 2.05
released 20 March 1997
Fixed silly bug in location of the HTML library files (notified by 
Jan Willamowius)
Changed embedded comment processing to improve chances of parsing code
with comments mixed in among function arguments (problems notified by
various users)
Implemented cccc_ign.dat configuration file to allow the user to instruct
the program to ignore inconvenient identifiers (usually these are synonyms
for keywords like 'extern' which are #defined in header files which CCCC
does not analyse).
Added some information on the cccc_ign.dat configuration file to the 
HTML library files.
Added Hermann H"uni's patch to the makefile for compilation on Solaris.

version 2.06
released 6 April 1997
Added support for various common C constructs, but probably still a long way
from good coverage of C.  Bill McLean contributed a patch which had much of
this, so many thanks to him.
Fixed the analyser so that unbalanced braces give a syntax error instead of
hanging the parser waiting forever at the end of file for the matching right 
brace to appear. This was notified in relation to code which had some 
conditional compilation constructs with unbalanced braces, which is ugly
but legal, so I thought I'd better support it.
Added an additional report focusing on the parts the parser couldn't parse.
This is probably the major enhancement for this release.





