File: FAQ

package info (click to toggle)
cxref 1.6e-1
  • links: PTS
  • area: main
  • in suites: jessie, jessie-kfreebsd
  • size: 2,592 kB
  • ctags: 2,123
  • sloc: ansic: 16,579; yacc: 2,091; sh: 917; lex: 470; perl: 452; makefile: 425; lisp: 256; cpp: 188; python: 80
file content (511 lines) | stat: -rw-r--r-- 19,743 bytes parent folder | download | duplicates (3)
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
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
          CXREF VERSION 1.6 - FREQUENTLY ASKED QUESTIONS AND ANSWERS
          ==========================================================

This file contains a list of frequently asked questions and their answers
relating to cxref version 1.6.

Not all of the questions here are real users questions, some of them have been
made up to give some help to people trying to use the program who find that the
README documentation is insufficient.

--------------------------------------------------------------------------------

Section 0 - Why doesn't this FAQ answer my question?

--------------------

Section 1 - What does cxref do (and what it doesn't)

Q 1.1   Does cxref support C++?
Q 1.2   Does cxref show which #includes that are not needed?
Q 1.3   Can cxref document automatic function variables?
Q 1.4   Does cxref run on systems other than UNIX?

--------------------

Section 2 - When cxref does not work

Q 2.1a  How do I find out what is causing the parse error?
Q 2.1b  What does this parse error message mean?
Q 2.2   Where is the file cxref.html referenced from README.html?
Q 2.3   Why are half of the cross references missing?
Q 2.4   Why can't cxref process my header file in isolation?
Q 2.5   Why can't LaTeX process the output files?
Q 2.6   Why does the include file name have the complete path name?
Q 2.7   Why does the include file name have the wrong path name?
Q 2.8   Why does cxref put in links to system include files?
Q 2.9   Why does xcref segfault processing some old K&R source files?

--------------------

Section 3 - How to make cxref do what you want

Q 3.1   How do I use cxref to process source files in more than one directory?
Q 3.2   How can I add my own information to the output files?
Q 3.3   Can I get a subset of the cross-reference information?
Q 3.4   Is there an easy way to generate the comments in the correct format?
Q 3.5   How do I produce LaTeX output from a single source.c.tex output file?
Q 3.6   How can I pass extra arguments to the C pre-processor?
Q 3.7   Can I cross-reference my source code at the same time as compiling it?
Q 3.8   What use is the .cxref configuration file?

--------------------

Section 4 - More information about cxref

Q 4.1   Who wrote cxref, When and Why?
Q 4.2   How do I find out more information about cxref?

--------------------------------------------------------------------------------

Section 0 - Why doesn't this FAQ answer my question?

This FAQ is released with each new version of the cxref program, so if the
question is one that is frequently asked about the new version then you will by
definition not find the answer here.

You can find the latest information about cxref at the cxref web-page, this
contains among other things a list of bug-fixes for the latest version.

http://www.gedanken.org.uk/software/cxref/

--------------------------------------------------------------------------------

Section 1 - What does cxref do (and what it doesn't)

--------------------

Q 1.1   Does cxref support C++?

No.

The cxref program only works for C, More specifically:

1) ANSI standard C with some leniency for common non-ANSI syntax.
        For example, the construct 'switch(foo) { case 1: ... default: }' is not
        ANSI, there must be a ';' after the default label, but it is accepted by
        cxref.

2) Traditional (K&R) function declarations, with implicit 'int' and 'void'.
        For example 'foo(){}' is parsed as if 'int foo(void){}' was specified.

3) The ability to parse GCC extensions.
        The GCC '__attribute__' and '__extension__' keywords and most of the
        other GCC extensions. The 'inline' keyword is allowed.

--------------------

Q 1.2   Does cxref show which #includes that are not needed?

No.

The output of the cxref program cross-references all of the functions,
variables, type definitions, included file etc.  There is not a way of
identifying files that are included in another source file that do not need to
be.

--------------------

Q 1.3   Can cxref document automatic function variables?

No.

The inclusion of automatic variables in the output is not included.  This is
because of the number of them in a typical function.  In theory it could be made
to do this.

--------------------

Q 1.4   Does cxref run on systems other than UNIX?

For example DOS / Win3 / Win95 / WinNT / OS/2.

UNIX    = Yes
        This is the system that the program way designed and initially written
        for, it should work on many versions of UNIX.
        I know that it works on Linux, SunOS 4.1.x, Solaris 2.x, AIX & HP-UX 10.

DOS/Win3 = No
        The program was not designed for DOS, the filenames used and the
        multi-process nature of the program do not allow this.

Win95/WinNT = Yes
        Using the Cygwin library and tools http://cygwin.com/ it is possible to
        compile and run the programs.

OS/2    = Maybe
        I have reports that it is possible with OS/2 Warp with emx, but I do not
        support cxref for this OS.

--------------------------------------------------------------------------------

Section 2 - When cxref does not work

--------------------

Q 2.1a  How do I find out what is causing the parse error?

The following error message is generated by cxref when parsing a source file
(with YYDEBUG set to 0 in parse-yy.h when cxref was compiled).

test.c:   4: parse error, expecting `','' or `';''
^^^^^^  ^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
file    line            type of error
name    number        generated by yacc

The error is on line 4 of the file test.c.  In this case, the error message that
the yacc parser is generating is of some help, more often the error message is
just 'parse error'.

If YYDEBUG was set to 1 in parse-yy.h, then a more detailed error message would
be given (See Q 2.1b).


Q 2.1b  What does this parse error message mean?

The following error message is generated by cxref when parsing a source file
(with YYDEBUG set to 1 in parse-yy.h when cxref was compiled).

test.c:   4: parse error, expecting `','' or `';''

The previous 10, current and next 10 symbols are:
 -8 | 296 :              INT : int
 -7 | 258 :       IDENTIFIER : foo
 -6 |  40 :                  : (
 -5 | 292 :             VOID : void
 -4 |  41 :                  : )
 -3 | 123 :                  : {
 -2 | 296 :              INT : int
 -1 | 258 :       IDENTIFIER : a
  0 | 296 :              INT : int
  1 | 258 :       IDENTIFIER : b
  2 |  59 :                  : ;
  3 | 125 :                  : }
END OF FILE
^^^               ^^^^^^^^^^  ^^^^^
symbol              symbol    symbol
number               type     value

From this we can reconstruct part of the file test.c, using the previous and
next 10 symbol values from the lexer.

int foo(void) { int a   int b; }
                      ^
This is where the parse error occurred, after 'int a' and before 'int b;'.
The cause of the error is now clear, there is a ';' missing after the
declaration of the variable a.

The cxref program is intended to be used on source files that are known to
compile with a C compiler.  In this case a parse error message should not be
seen except for either non-standard C, (and compiler) or a bug in cxref.

--------------------

Q 2.2   Where is the file cxref.html referenced from README.html?

The README.html file has a reference to the file cxref.html, this file is only
present when 'make docs' has been run to generate the cross references for the
cxref program itself.  The file is in the example sub-directory of the doc
directory.

--------------------

Q 2.3   Why are half of the cross references missing?

The way that cxref works is that it processes all of the source files for a
program, one at a time and generates a cross reference database.  A second pass
of the program is required to generate all of the cross references from the
database of cross reference information.

For this reason, the Makefile for the doc directory of cxref uses 'cxref *.c
-xref -Odoc' for the first pass and 'cxref *.c -xref -Odoc -html -latex' for the
second pass.  The first to build the database, the second to produce the
outputs.

The reason that the cross references are missing is that only one pass of the
program has been done on all of the files.  The later files to be be processed
will have cross references for the earlier files processed.

--------------------

Q 2.4   Why can't cxref process my header file in isolation?

The cxref program needs to process the header files to enable a cross reference
for them to be generated.  In many cases, the header file will not have been
written with this in mind, and may rely on other header files being included
before the one being processed.  The best solution to this is to modify the
header file so that it includes all of the header files that it needs.

Another option is to use '-- -include filename.h' on the command line.  This
will include the specified file (filename.h) into the source file that is being
processed at the beginning.

There is a Perl script supplied with the cxref source files called fixheader.
This can be used to automatically determine what header files may be required.
The decision is based on the header files that are used for the files that cxref
can process and lots of test compilations.

--------------------

Q 2.5   Why can't LaTeX process the output files?

The LaTeX output is designed to work with LaTeX version 2e and the output files
will not work with the much older LaTeX version 2.0.9.

The file cxref.tex (or basename.tex if '-Nbasename' is used) is the file that
must be processed by LaTeX.

--------------------

Q 2.6   Why does the include file name have the complete path name?

This is because a standard C preprocessor is being used instead of cxref-cpp or
an appropriate version of gcc.  Changes were made in version 2.8.0 of gcc that
make it output the names of the include files as they are in the original source
code and not after the files have been translated into an absolute pathname.

--------------------

Q 2.7   Why does the include file name have the wrong path name?

If the answer to this question is not the same as the answer to Q 2.6 then it
could be the following.  When the files that are being cross-referenced are in a
directory that contains a symbolic link in the path then the current directory
has two (or more) possible names.  The way that the cxref program works is that
it finds the current working directory (which is the real pathname, not using
any links).  If the name that you specify using -R is another name for the same
directory then cxref will not realise that they are the same.  This can cause
the pathnames to become confused.  Try using relative pathnames where possible
for the -R and -I options.

--------------------

Q 2.8   Why does cxref put in links to system include files?

The way that cxref knows which include files are local to the program and which
ones are system ones is by the way that they are included.  Any that use double
quotes '"' are local ones and wil have links to them included in the cross
reference output.  The include files that use the angle brackets '<>' are system
files and do not have links to them included.

The best solution is to change the include files so that the distinction is
clear.  An alternative is to use the '-isystem DIRNAME' option of gcc.  This
will cause gcc to treat files in this directory as if they are system files.
Since cxref uses gcc for the pre-processing, this option can be passed through
using 'cxref file.c -- -isystem DIRNAME'.

--------------------

Q 2.9	Why does xcref segfault processing some old K&R source files?

Quite possibly this is due a known issue with K&R function definitions that
include a function pointer as an argument. To attempt a fix for this in the
parser this might likely break something else in the parser.
Here is an example:

int
caller (s1, s2, comp)
char *s1;
char *s2;
int (*comp)(void*,void*);
{
/*....*/
}

Change to ansi C syntax, such as:

int
caller (char *s1, char *s2, int (*comp)(void*,void*))
{
/*...*/
}

Now, barring syntax errors else where in the source file, this should parse
without problems. 

--------------------------------------------------------------------------------

Section 3 - How to make cxref do what you want

--------------------

Q 3.1   How do I use cxref to process source files in more than one directory?

The cxref program depends on a database of cross references, these must all be
consistent.  This requires that all of the files to be cross referenced are in
the same directory tree.

Example:

directory     files
- - - - -     - - -
basedir    :  f0.c f0.h ...
 |- s1     :  f1.c f1.h ...
 |- s2     :  f2.c f2.h ...
...

-- f2.c --
#include <...>
#include "f2.h"
#include "../s1/f1.h"
#include "f0.h"
----------

In the base directory 'basedir' run 'cxref -xref -Odoc s2/f2.c -html -I.'.  This
will create the file 'doc/s2/f2.c.html' for the file 'f2.c' and this will
contain references to the files 'doc/s2/f2.h.html', 'doc/s1/f1.h.html' and
'doc/f0.h.html'.  The subdirectories 'doc/s1', 'doc/s2' will be automatically
created within the 'doc' directory to put the files into (the 'doc' directory
must already exist).

directory        files
- - - - -        - - -
basedir
 |- doc       :  f0.c.html f0.h.html ... cxref.html
     |- s1    :  f1.c.html f1.h.html ...
     |- s2    :  f2.c.html f2.h.html ...
...

An alternative method is to use the -R option to cxref.  In the directory 's2',
cxref can be run as 'cxref -R.. -xref -Odoc f2.c -html -I.'.  This will change
directory to '..' ('basedir') before cxref is run, and will modify the cxref
arguments so that it is equivalent to running cxref from 'basedir' as detailed
above.

--------------------

Q 3.2   How can I add my own information to the output files?

The files cxref.html and cxref.tex (depending on whether using HTML or LaTeX
format and the use of the '-Nbasename' option) are the ones to edit.  These
files contain the lines 'Begin-Of-Source-Files' and 'End-Of-Source-Files' as
comments.  The output files for each source file are automatically included
between these lines if they do not already exist there.  The order of these
files and any other text between these lines is not important.  Customisation of
the files should be added here.  The output files for each source file are
automatically generated so any edits made to these will be lost when cxref is
run.

--------------------

Q 3.3   Can I get a subset of the cross-reference information?

At the moment, the only one way to limit the amount of cross referencing is to
use the '-xref-*' command line option (see README).  There are plans for a
future version of cxref to have an options file that would allow different
amounts of information to be generated in the output.  For example, only to
display called and not calls information for each function.

--------------------

Q 3.4   Is there an easy way to generate the comments in the correct format?

The only easy way to do this is to use the cxref.el macro file and Emacs.  This
is what is used to generate the comments in the cxref source code itself.

--------------------

Q 3.5   How do I produce LaTeX output from a single source.c.tex output file?

The file cxref.tex (or basename.tex if '-Nbasename' is used) is the file that
must be processed by LaTeX.  All of the individual LaTeX files for the source
files are included into this file.  If an individual file source.c.tex needs to
be processed then a copy of the file cxref.tex should be modified to include
only the required source.c.tex file.

--------------------

Q 3.6   How can I pass extra arguments to the C pre-processor?

The cxref program itself has three ways that you can specify the arguments that
are passed to the C pre-processor.

a) The -CPP option allows the name of the pre-processor program itself to be
   changed.
   e.g. 'cxref -CPP "/usr/foo/cpp -C" foo.c' will use the cpp from /usr/foo
   instead of the compiled in default and pass it the option -C.

b) The most common C pre-processor commands are recognised by cxref
   automatically, these are -D*, -U* and -I*.

c) Any amount of extra options can be passed to the preprocessor by appending
   them to the command line after the end-of-arguments marker '--'.
   e.g. 'cxref foo.c -- -traditional' will pass -traditional to the
   pre-processor.

--------------------

Q 3.7   Can I cross-reference my source code at the same time as compiling it?

It is possible to cross-reference and document your source code at the same time
as compiling it by using the cxref-cc script.  This takes the same arguments as
your usual C compiler and performs both functions.

First it calls the C compiler and passes on all of the command line arguments.
The real C compiler is specified by the CXREFCC environment variable, or the CC
environment variable or it will use gcc if neither of these are set.

Second the arguments that cxref needs to have are extracted from the arguments
that the C compiler had and cxref is called.  The arguments that are kept are
the -D*, -U*, -I* arguments to specify #defines and #include paths, and the file
name of the source file itself.  Any other arguments are taken from the .cxref
file (See Q 3.8).

After doing this it will still be necessary to sort out the header files since
these are not cross-referenced using this method.

--------------------

Q 3.8   What use is the .cxref configuration file?

The most obvious use is if you have a lot of command line options that you don't
want to have to enter every time that you run the program.

However the .cxref file is most useful when you have a multiple directory source
tree (See< Q 3.1), or when you are using an existing Makefile to build
documentation.

When there are various subdirectories containing source code, a .cxref file in
each sub-directory can be used just containing the line '-R..' or whatever is
appropriate to point cxref to the root of the source tree.  This means that
there is no need to keep track of which directory you are in, they all will use
the correct directory to work from.

If you already have a Makefile that goes through all of the source code then you
may want to modify it so that it calls cxref instead of calling the C compiler.
This means that there is no room to put the extra arguments to cxref on the
command line.  A .cxref file can contain the command line arguments so that you
only need to need the arguments that are already there for the C compiler
(See Q 3.7).

--------------------------------------------------------------------------------

Section 4 - More information about cxref

--------------------

Q 4.1   Who wrote cxref, When and Why?

The cxref program was written by Andrew M. Bishop in 1995-2004 and maintained
since then.

An earlier program by the same author using basically the same comment
convention was written in Emacs Lisp in 1994.  This version was slow, the amount
of cross referencing was poor and the output was only in troff format.  The
current C program was written to replace this but has grown to become much
better in the cross referencing that is done and the format of the output has
increased greatly.

The cxref program can be freely distributed according to the terms of the GNU
General Public License (see the file `COPYING').

--------------------

Q 4.2   How do I find out more information about cxref?

There is a cxref homepage at http://www.gedanken.org.uk/software/cxref/.  This
is kept updated with news about the program, as new versions become available.

The web page also contains contact information for reporting bugs by e-mail.

--------------------------------------------------------------------------------