tools/cxref/cpp/README

   1        C Cross Referencing & Documenting tool Version 1.5 - cxref-cpp
   2        ==============================================================
   3
   4 If you have gcc version 2.8.0 or later installed then you do not need to use
   5 this program although you may chose to do so.
   6
   7 There are problems with gcc version 3.3 (and others?) where comments that follow
   8 on the same line as a #define statement or a #include statement are lost.  If
   9 you are using one of these versions of gcc then using cxref-cpp is the only way
  10 to keep all of these comments.
  11
  12
  13 This program is a copy of the gcc-2.7.2 pre-processor with some modifications to
  14 make cxref work better.  Some of the changes were put back into gcc version 2.8.0.
  15
  16 The files are modified in the following way.
  17
  18 cccp.c    - Hacked about a bit (the changes are in cccp.c.diff).
  19 cexp.y    - As original.
  20 version.c - Change the version number to indicate that it is modified.
  21 pcp.h     - As original.
  22 config.h  - A simple version that should work in most cases.
  23 tm.h      - A simple version that should work in most cases.
  24
  25
  26 Configuration
  27 -------------
  28
  29 There is a standard GNU configure script that should be used to configure
  30 cxref-cpp.  This is normally called by the configure script in the main
  31 directory.
  32
  33 If the automatic configuration fails then the information in the following
  34 sections detail what the configure script works out.  The information is put
  35 into the Makefile automatically, only in the case of a problem should it be
  36 changed manually.
  37
  38
  39 PREDEFINES and INCLUDE_DIR[123]
  40 -------------------------------
  41
  42 [Note that what follows applies to gcc, other compilers may be different]
  43
  44 The cxref-cpp program needs to have the same include directories and predefined
  45 macros built in to the program as gcc.  This is so that cxref-cpp and gcc have
  46 the same behaviour when processing the source files.
  47
  48 Use `gcc -E -v -dM - < /dev/null' to see the list of include paths and
  49 predefined macros.
  50
  51 Those marked `->' below are important.
  52
  53      | Reading specs from /usr/lib/gcc-lib/i486-linux/2.5.8/specs
  54      | gcc version 2.5.8
  55 C -> |  /usr/lib/gcc-lib/i486-linux/2.5.8/cpp -lang-c -v -undef \
  56         -D__GNUC__=2 -D__GNUC_MINOR__=5 -Dunix -Di386 -Dlinux -D__unix__ \
  57         -D__i386__ -D__linux__ -D__unix -D__i386 -D__linux -D__i486__ \
  58         -Asystem(unix) -Asystem(posix) -Acpu(i386) -Amachine(i386) \
  59         -dM -
  60      | GNU CPP version 2.5.8 (80386, BSD syntax)
  61      | #include "..." search starts here:
  62      | #include <...> search starts here:
  63 I1-> |  /usr/local/include
  64 I2-> |  /usr/i486-linux/include
  65 I3-> |  /usr/lib/gcc-lib/i486-linux/2.5.8/include
  66      |  /usr/include
  67      | End of search list.
  68      | #define __linux__ 1
  69      | #define linux 1
  70      | #define __i386__ 1
  71      | #define __i386 1
  72      | #define __GNUC_MINOR__ 5
  73      | #define __i486__ 1
  74      | #define i386 1
  75      | #define __unix 1
  76      | #define __unix__ 1
  77      | #define __GNUC__ 2
  78      | #define __linux 1
  79      | #define unix 1
  80
  81
  82 C   The command line that is used when gcc calls cpp.  Notice that it includes
  83     a number of flags that change the default action of cpp.  (Try doing
  84     'cpp -v -dM - < /dev/null' to see the difference.)
  85     Note the -D... and -A... command line flags, the PREDEFINES variable in
  86     cxref-cpp-configure needs to be set equal to these.
  87
  88 I*  The include files that are built into the cpp program.
  89     Add these to the cxref-cpp-configure script as described below:
  90
  91     I1  =>  INCLUDE_DIR1
  92     I2  =>  INCLUDE_DIR2
  93     I3  =>  INCLUDE_DIR3
  94
  95
  96 Testing
  97 -------
  98
  99 When cxref-cpp has been made use 'cxref-cpp -v -dM - < /dev/null' and check that
 100 the include directories and predefines are the same as those for gcc by using
 101 'gcc -E -v -dM - < /dev/null'.
 102
 103 If there are differences then it is possible that the cxref-cpp program will
 104 fail even though the source file is legal.