C Cross Referencing & Documenting tool Version 1.6a - cxref-cpp =============================================================== Introduction ------------ This pre-processor is a modified version of the gcc-2.95.3 pre-processor with modifications to make cxref work better. Previous versions of cxref used the pre-processor from gcc-2.7.2. History ------- Depending on the version of gcc that you have installed you may, or may not, need to use this program as the cxref pre-processor. In those cases where you can use your existing gcc version you may still wish to use this program. The table below shows the need for this program depending on the version of gcc installed. GCC version Need for cxref-cpp ----------- ------------------ none Yes (1) < 2.8.0 Yes (1) 2.8.0 - 2.95.3 (?) Optional (not used by default) (2) 3.0.0 (?) - 3.x.y Recommended (used by default) (3) (1) If you do not have gcc installed or it is a version before 2.8.0 then you will need to use cxref-cpp as the pre-processor or the cxref program will not be able to work. This pre-processor includes modifications to pass more information about the original source code through to the output. (2) With gcc version 2.8.0 the required modifications to the pre-processor were included into the mainline of gcc. (3) With gcc version 3.0.0 there was a rewrite of the pre-processor and some of the modifications that were included in version 2.8.0 were removed of modified. In particular the changes that were made mean that comments that follow on the same line as a #define statement or a #include statement are lost. See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13726 and http://gcc.gnu.org/bugzilla/show_bug.cgi?id=14342 for gcc bug reports. Implementation -------------- This program is a copy of the gcc-2.95.3 pre-processor with some modifications that allow it to use the built-in pre-processor definitions from any other version of gcc. The files are modified in the following way. ansidecl.h - Unmodified original from gcc-2.95.3. cexp.c - Unmodified original from gcc-2.95.3. cexp.y - Unmodified original from gcc-2.95.3. gansidecl.h - Unmodified original from gcc-2.95.3. intl.h - Unmodified original from gcc-2.95.3. pcp.h - Unmodified original from gcc-2.95.3. prefix.h - Unmodified original from gcc-2.95.3. system.h - Unmodified original from gcc-2.95.3. libiberty.h - Empty file required for inclusion in system.h prefix.c - Modified from gcc-2.95.3 * Added function prototype. version.c - Modified from gcc-2.95.3 * Version number indicates cxref specific version. cccp.c - Modified from gcc-2.95.3 * Changed to work with cxref . New -cxref-cpp-defines option. . Allow gcc 3.x "-Afoo=bar" options. . Skip standard #defines. . No built-in include paths. * Debian/egcs patch to handle DOS newlines after backslash. config.h - A replacement for the original that has miscellaneous definitions missing from elsewhere and includes the autoconfig.h file. 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. The configure script takes two options that control the usage of this program or the installed gcc pre-processor: --with-cxref-cpp and --without-cxref-cpp. By default the configure script will decide if the installed gcc will work fully on its own. The option --with-cxref-cpp will override this decision and force cxref-cpp to be used even if the version of gcc is suitable. The option --without-cxref-cpp will override the automatic decision and force gcc to be used even if it is not suitable. If the automatic configuration fails then the information in the following sections detail what the cxref-cpp-configure script works out. The information is put into the runtime configuration file (cxref-cpp.defines) automatically, only in the case of a problem should it be changed manually. PREDEFINES, INCLUDES and DEFINES -------------------------------- [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 P -> | /usr/lib/gcc-lib/i486-linux/2.5.8/cpp -lang-c -v -undef \ -D__GNUC__=2 -D__GNUC_MINOR__=95 -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: I -> | /usr/local/include I -> | /usr/i486-linux/include I -> | /usr/lib/gcc-lib/i486-linux/2.5.8/include I -> | /usr/include | End of search list. D -> | #define __linux__ 1 D -> | #define linux 1 D -> | #define __i386__ 1 D -> | #define __i386 1 D -> | #define __GNUC_MINOR__ 5 D -> | #define __i486__ 1 D -> | #define i386 1 D -> | #define __unix 1 D -> | #define __unix__ 1 D -> | #define __GNUC__ 2 D -> | #define __linux 1 D -> | #define unix 1 P 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, these are the PREDEFINES. I The include files that are built into the cpp program. This list of directories are the INCLUDES. D The pre-defined #defines used for all pre-processing. This list of #defines are the DEFINES. The cxref-cpp runtime configuration file cxref-cpp.defines is created from the PREDEFINES, INCLUDES and DEFINES. Each item in the PREDEFINES list appears following a C++ comment '//' and a space character, each item in the INCLUDES list appears following a C++ comment, a space and '-I' and each item in the DEFINES list appears on a line on its own. For the example output above the cxref-cpp.defines file would look like the following: // -D__GNUC__=2 // -D__GNUC_MINOR__=95 // -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) // -I/usr/local/include // -I/usr/i486-linux/include // -I/usr/lib/gcc-lib/i486-linux/2.5.8/include // -I/usr/include #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 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'. You will need to run cxref-cpp with the option '-cxref-cpp-defines ./cxref-cpp.defines' if you have not installed the file cxref-cpp.defines.