File: README

package info (click to toggle)
cxref 1.6a-1.1
  • links: PTS
  • area: main
  • in suites: etch, etch-m68k
  • size: 2,124 kB
  • ctags: 1,502
  • sloc: ansic: 18,209; yacc: 2,086; sh: 917; lex: 460; perl: 452; makefile: 418; lisp: 256; cpp: 188; python: 80
file content (211 lines) | stat: -rw-r--r-- 7,659 bytes parent folder | download | duplicates (7)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
       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.