       C Cross Referencing & Documenting tool Version 1.5 - cxref-cpp
       ==============================================================

If you have gcc version 2.8.0 or later installed then you do not need to use
this program although you may chose to do so.

There are problems with gcc version 3.3 (and others?) where comments that follow
on the same line as a #define statement or a #include statement are lost.  If
you are using one of these versions of gcc then using cxref-cpp is the only way
to keep all of these comments.


This program is a copy of the gcc-2.7.2 pre-processor with some modifications to
make cxref work better.  Some of the changes were put back into gcc version 2.8.0.

The files are modified in the following way.

cccp.c    - Hacked about a bit (the changes are in cccp.c.diff).
cexp.y    - As original.
version.c - Change the version number to indicate that it is modified.
pcp.h     - As original.
config.h  - A simple version that should work in most cases.
tm.h      - A simple version that should work in most cases.


Configuration
-------------

There is a standard GNU configure script that should be used to configure
cxref-cpp.  This is normally called by the configure script in the main
directory.

If the automatic configuration fails then the information in the following
sections detail what the configure script works out.  The information is put
into the Makefile automatically, only in the case of a problem should it be
changed manually.


PREDEFINES and INCLUDE_DIR[123]
-------------------------------

[Note that what follows applies to gcc, other compilers may be different]

The cxref-cpp program needs to have the same include directories and predefined
macros built in to the program as gcc.  This is so that cxref-cpp and gcc have
the same behaviour when processing the source files.

Use `gcc -E -v -dM - < /dev/null' to see the list of include paths and
predefined macros.

Those marked `->' below are important.

     | Reading specs from /usr/lib/gcc-lib/i486-linux/2.5.8/specs
     | gcc version 2.5.8
C -> |  /usr/lib/gcc-lib/i486-linux/2.5.8/cpp -lang-c -v -undef \
        -D__GNUC__=2 -D__GNUC_MINOR__=5 -Dunix -Di386 -Dlinux -D__unix__ \
        -D__i386__ -D__linux__ -D__unix -D__i386 -D__linux -D__i486__ \
        -Asystem(unix) -Asystem(posix) -Acpu(i386) -Amachine(i386) \
        -dM -
     | GNU CPP version 2.5.8 (80386, BSD syntax)
     | #include "..." search starts here:
     | #include <...> search starts here:
I1-> |  /usr/local/include
I2-> |  /usr/i486-linux/include
I3-> |  /usr/lib/gcc-lib/i486-linux/2.5.8/include
     |  /usr/include
     | End of search list.
     | #define __linux__ 1 
     | #define linux 1 
     | #define __i386__ 1 
     | #define __i386 1 
     | #define __GNUC_MINOR__ 5 
     | #define __i486__ 1 
     | #define i386 1 
     | #define __unix 1 
     | #define __unix__ 1 
     | #define __GNUC__ 2 
     | #define __linux 1 
     | #define unix 1 


C   The command line that is used when gcc calls cpp.  Notice that it includes
    a number of flags that change the default action of cpp.  (Try doing
    'cpp -v -dM - < /dev/null' to see the difference.)
    Note the -D... and -A... command line flags, the PREDEFINES variable in
    cxref-cpp-configure needs to be set equal to these.

I*  The include files that are built into the cpp program.
    Add these to the cxref-cpp-configure script as described below:

    I1  =>  INCLUDE_DIR1
    I2  =>  INCLUDE_DIR2
    I3  =>  INCLUDE_DIR3


Testing
-------

When cxref-cpp has been made use 'cxref-cpp -v -dM - < /dev/null' and check that
the include directories and predefines are the same as those for gcc by using
'gcc -E -v -dM - < /dev/null'.

If there are differences then it is possible that the cxref-cpp program will
fail even though the source file is legal.
