| blob | fbb9fd62f9e5e28a5469e6117f768a11333ccc9b |
2 <HTML>
4 <HEAD>
6 </HEAD>
8 <BODY>
12 This file contains a list of frequently asked questions and their answers
13 relating to cxref version 1.5.
15 Not all of the questions here are real users questions, some of them have been
16 made up to give some help to people trying to use the program who find that the
17 README documentation is insufficient.
18 <hr>
28 <p><a href="#Q-2.2">Q 2.2 Where are files doc/cxref.html & FAQ.html referenced from README.html?</a>
36 <p><a href="#Q-3.1">Q 3.1 How do I use cxref to process source files in more than one directory?</a>
39 <p><a href="#Q-3.4">Q 3.4 Is there an easy way to generate the comments in the correct format?</a>
40 <p><a href="#Q-3.5">Q 3.5 How do I produce LaTeX output from a single source.c.tex output file?</a>
42 <p><a href="#Q-3.7">Q 3.7 Can I cross-reference my source code at the same time as compiling it?</a>
47 <hr>
50 This FAQ is released with each new version of the cxref program, so if the
51 question is one that is frequently asked about the new version then you will by
52 definition not find the answer here.
54 You can find the latest information about cxref at the cxref web-page, this
55 contains among other things a list of bug-fixes for the latest version.
57 <hr>
60 <pre>
61 No.
63 The cxref program only works for C, More specifically:
65 1) ANSI standard C with some leniency for common non-ANSI syntax.
66 For example, the construct 'switch(foo) { case 1: ... default: }' is not
67 ANSI, there must be a ';' after the default label, but it is accepted by
68 cxref.
71 For example 'foo(){}' is parsed as if 'int foo(void){}' was specified.
73 3) The ability to parse GCC extensions.
74 The GCC '__attribute__' and '__extension__' keywords and most of the
75 other GCC extensions. The 'inline' keyword is allowed.
76 </pre>
78 <pre>
79 No.
81 The output of the cxref program cross-references all of the functions,
82 variables, type definitions, included file etc. There is not a way of
83 identifying files that are included in another source file that do not need to
84 be.
85 </pre>
87 <pre>
88 No.
90 The inclusion of automatic variables in the output is not included. This is
91 because of the number of them in a typical function. In theory it could be made
92 to do this.
93 </pre>
95 <pre>
96 For example DOS / Win3 / Win95 / WinNT / OS/2.
98 UNIX = Yes
99 This is the system that the program way designed and initially written
100 for, it should work on many versions of UNIX.
103 DOS/Win3 = No
104 The program was not designed for DOS, the filenames used and the
105 multi-process nature of the program do not allow this.
107 Win95/WinNT = Yes
108 Using the Cygwin library and tools <a href="http://sourceware.cygnus.com/cygwin/">http://sourceware.cygnus.com/cygwin/</a>
109 it is possible to compile and run the programs.
111 OS/2 = Maybe
112 I have reports that it is possible with OS/2 Warp with emx, but I do not
113 support cxref for this OS.
114 </pre>
115 <hr>
118 <pre>
119 The following error message is generated by cxref when parsing a source file
120 (with YYDEBUG set to 0 in parse-yy.h when cxref was compiled).
122 test.c: 4: parse error, expecting `','' or `';''
123 ^^^^^^ ^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
124 file line type of error
125 name number generated by yacc
127 The error is on line 4 of the file test.c. In this case, the error message that
128 the yacc parser is generating is of some help, more often the error message is
129 just 'parse error'.
131 If YYDEBUG was set to 1 in parse-yy.h, then a more detailed error message would
133 </pre>
135 <pre>
136 The following error message is generated by cxref when parsing a source file
137 (with YYDEBUG set to 1 in parse-yy.h when cxref was compiled).
139 test.c: 4: parse error, expecting `','' or `';''
154 END OF FILE
155 ^^^ ^^^^^^^^^^ ^^^^^
156 symbol symbol symbol
157 number type value
159 From this we can reconstruct part of the file test.c, using the previous and
160 next 10 symbol values from the lexer.
162 int foo(void) { int a int b; }
163 ^
164 This is where the parse error occurred, after 'int a' and before 'int b;'.
165 The cause of the error is now clear, there is a ';' missing after the
166 declaration of the variable a.
168 The cxref program is intended to be used on source files that are known to
169 compile with a C compiler. In this case a parse error message should not be
170 seen except for either non-standard C, (and compiler) or a bug in cxref.
171 </pre>
172 <h3><a name="Q-2.2">Q 2.2 Where are files doc/cxref.html & FAQ.html referenced from README.html?</a></h3>
173 <pre>
174 The README.html file has a reference to the files doc/cxref.html and FAQ.html
175 these files are only present when 'make docs' has been run to generate the cross
176 references for the cxref program itself.
177 </pre>
179 <pre>
180 The way that cxref works is that it processes all of the source files for a
181 program, one at a time and generates a cross reference database. A second pass
182 of the program is required to generate all of the cross references from the
183 database of cross reference information.
185 For this reason, the Makefile for the doc directory of cxref uses 'cxref *.c
186 -xref -Odoc' for the first pass and 'cxref *.c -xref -Odoc -html -latex' for the
187 second pass. The first to build the database, the second to produce the
188 outputs.
190 The reason that the cross references are missing is that only one pass of the
191 program has been done on all of the files. The later files to be be processed
192 will have cross references for the earlier files processed.
193 </pre>
195 <pre>
196 The cxref program needs to process the header files to enable a cross reference
197 for them to be generated. In many cases, the header file will not have been
198 written with this in mind, and may rely on other header files being included
199 before the one being processed. The best solution to this is to modify the
200 header file so that it includes all of the header files that it needs.
202 Another option is to use '-- -include filename.h' on the command line. This
203 will include the specified file (filename.h) into the source file that is being
204 processed at the beginning.
206 There is a Perl script supplied with the cxref source files called fixheader.
207 This can be used to automatically determine what header files may be required.
208 The decision is based on the header files that are used for the files that cxref
209 can process and lots of test compilations.
210 </pre>
212 <pre>
213 There are two options for producing LaTeX output, '-latex' and '-latex2e'.
214 These refer to two different versions of the LaTeX program. The first is for
217 The file cxref.tex (or basename.tex if '-Nbasename' is used) is the file that
218 must be processed by LaTeX.
219 </pre>
221 <pre>
222 This is because a standard C preprocessor is being used instead of cxref-cpp or
223 an appropriate version of gcc. One of the changes to the recent versions of gcc
224 (2.8.0) has been made to the GNU cccp to make cxref-cpp. This is to make it
225 output the names of the include files as they are in the original source code
226 and not after the files have been translated into an absolute pathname.
227 </pre>
229 <pre>
230 If the answer to this question is not the same as the answer to Q 2.6 then it
231 could be the following. When the files that are being cross-referenced are in a
232 directory that contains a symbolic link in the path then the current directory
233 has two (or more) possible names. The way that the cxref program works is that
234 it finds the current working directory (which is the real pathname, not using
235 any links). If the name that you specify using -R is another name for the same
236 directory then cxref will not realise that they are the same. This can cause
237 the pathnames to become confused. Try using relative pathnames where possible
238 for the -R and -I options.
239 </pre>
241 <pre>
242 The way that cxref knows which include files are local to the program and which
243 ones are system ones is by the way that they are included. Any that use double
244 quotes '"' are local ones and wil have links to them included in the cross
245 reference output. The include files that use the angle brackets '<>' are system
246 files and do not have links to them included.
248 The best solution is to change the include files so that the distinction is
249 clear. An alternative is to use the '-isystem DIRNAME' option of gcc. This
250 will cause gcc to treat files in this directory as if they are system files.
251 Since cxref uses gcc for the pre-processing, this option can be passed through
252 using 'cxref file.c -- -isystem DIRNAME'.
253 </pre>
254 <hr>
256 <h3><a name="Q-3.1">Q 3.1 How do I use cxref to process source files in more than one directory?</a></h3>
257 <pre>
258 The cxref program depends on a database of cross references, these must all be
259 consistent. This requires that all of the files to be cross referenced are in
260 the same directory tree.
262 Example:
264 directory files
265 - - - - - - - -
266 basedir : f0.c f0.h ...
267 |- s1 : f1.c f1.h ...
268 |- s2 : f2.c f2.h ...
269 ...
271 -- f2.c --
272 #include <...>
276 ----------
278 In the base directory 'basedir' run 'cxref -xref -Odoc s2/f2.c -html -I.'. This
279 will create the file 'doc/s2/f2.c.html' for the file 'f2.c' and this will
280 contain references to the files 'doc/s2/f2.h.html', 'doc/s1/f1.h.html' and
281 'doc/f0.h.html'. The subdirectories 'doc/s1', 'doc/s2' will be automatically
282 created within the 'doc' directory to put the files into (the 'doc' directory
283 must already exist).
285 directory files
286 - - - - - - - -
287 basedir
288 |- doc : f0.c.html f0.h.html ... cxref.html
289 |- s1 : f1.c.html f1.h.html ...
290 |- s2 : f2.c.html f2.h.html ...
291 ...
293 An alternative method is to use the -R option to cxref. In the directory 's2',
294 cxref can be run as 'cxref -R.. -xref -Odoc f2.c -html -I.'. This will change
295 directory to '..' ('basedir') before cxref is run, and will modify the cxref
296 arguments so that it is equivalent to running cxref from 'basedir' as detailed
297 above.
298 </pre>
300 <pre>
301 The files cxref.html and cxref.tex (depending on whether using HTML or LaTeX
302 format and the use of the '-Nbasename' option) are the ones to edit. These
303 files contain the lines 'Begin-Of-Source-Files' and 'End-Of-Source-Files' as
304 comments. The output files for each source file are automatically included
305 between these lines if they do not already exist there. The order of these
306 files and any other text between these lines is not important. Customisation of
307 the files should be added here. The output files for each source file are
308 automatically generated so any edits made to these will be lost when cxref is
309 run.
310 </pre>
312 <pre>
313 At the moment, the only one way to limit the amount of cross referencing is to
314 use the '-xref-*' command line option (see README). There are plans for a
315 future version of cxref to have an options file that would allow different
316 amounts of information to be generated in the output. For example, only to
317 display called and not calls information for each function.
318 </pre>
319 <h3><a name="Q-3.4">Q 3.4 Is there an easy way to generate the comments in the correct format?</a></h3>
320 <pre>
321 The only easy way to do this is to use the cxref.el macro file and Emacs. This
322 is what is used to generate the comments in the cxref source code itself.
323 </pre>
324 <h3><a name="Q-3.5">Q 3.5 How do I produce LaTeX output from a single source.c.tex output file?</a></h3>
325 <pre>
326 The file cxref.tex (or basename.tex if '-Nbasename' is used) is the file that
327 must be processed by LaTeX. All of the individual LaTeX files for the source
328 files are included into this file. If an individual file source.c.tex needs to
329 be processed then a copy of the file cxref.tex should be modified to include
330 only the required source.c.tex file.
331 </pre>
333 <pre>
334 The cxref program itself has three ways that you can specify the arguments that
335 are passed to the C pre-processor.
337 a) The -CPP option allows the name of the pre-processor program itself to be
338 changed.
340 instead of the compiled in default and pass it the option -C.
342 b) The most common C pre-processor commands are recognised by cxref
343 automatically, these are -D*, -U* and -I*.
345 c) Any amount of extra options can be passed to the preprocessor by appending
346 them to the command line after the end-of-arguments marker '--'.
347 e.g. 'cxref foo.c -- -traditional' will pass -traditional to the
348 pre-processor.
349 </pre>
350 <h3><a name="Q-3.7">Q 3.7 Can I cross-reference my source code at the same time as compiling it?</a></h3>
351 <pre>
352 It is possible to cross-reference and document your source code at the same time
353 as compiling it by using the cxref-cc script. This takes the same arguments as
354 your usual C compiler and performs both functions.
356 First it calls the C compiler and passes on all of the command line arguments.
357 The real C compiler is specified by the CXREFCC environment variable, or the CC
358 environment variable or it will use gcc if neither of these are set.
360 Second the arguments that cxref needs to have are extracted from the arguments
361 that the C compiler had and cxref is called. The arguments that are kept are
362 the -D*, -U*, -I* arguments to specify #defines and #include paths, and the file
363 name of the source file itself. Any other arguments are taken from the .cxref
366 After doing this it will still be necessary to sort out the header files since
367 these are not cross-referenced using this method.
368 </pre>
370 <pre>
371 The most obvious use is if you have a lot of command line options that you don't
372 want to have to enter every time that you run the program.
374 However the .cxref file is most useful when you have a multiple directory source
375 tree (See< Q 3.1), or when you are using an existing Makefile to build
376 documentation.
378 When there are various subdirectories containing source code, a .cxref file in
379 each sub-directory can be used just containing the line '-R..' or whatever is
380 appropriate to point cxref to the root of the source tree. This means that
381 there is no need to keep track of which directory you are in, they all will use
382 the correct directory to work from.
384 If you already have a Makefile that goes through all of the source code then you
385 may want to modify it so that it calls cxref instead of calling the C compiler.
386 This means that there is no room to put the extra arguments to cxref on the
387 command line. A .cxref file can contain the command line arguments so that you
388 only need to need the arguments that are already there for the C compiler
390 </pre>
391 <hr>
394 <pre>
395 The cxref program was written by Andrew M. Bishop (amb@gedanken.demon.co.uk) in
396 1995,96,97,98,99 and maintained since then.
398 There is a cxref home-page on the World Wide Web, available via the author's
399 home-page at <a href="http://www.gedanken.demon.co.uk/">http://www.gedanken.demon.co.uk/</a> . This is kept updated with news
400 about the program, as new versions become available.
402 An earlier program by the same author using basically the same comment
403 convention was written in Emacs Lisp in 1994. This version was slow, the amount
404 of cross referencing was poor and the output was only in troff format. The
405 current C program was written to replace this but has grown to become much
406 better in the cross referencing that is done and the format of the output has
407 increased greatly.
409 The cxref program can be freely distributed according to the terms of the GNU
410 General Public License (see the file `COPYING').
411 </pre>
413 <pre>
414 By e-mail, send them to me at amb@gedanken.demon.co.uk and put cxref somewhere
415 in the subject line. You can also report bugs or provide comments via the
416 feedback form on the cxref home-page on the World Wide Web accessible via
419 Before doing this, you should check the FAQ and the cxref web-page to see if the
420 answer is there. If it is not, and it is a parse error then check that it is a
421 cxref problem and not a syntax error in the source file.
422 When you are sure that it is a cxref bug, give me as much information as you
423 can, about the error, when it happens, what system you are using etc. It is
424 useful if you can provide a small example and the output of using the '-raw'
425 option to provide the actual output that you are seeing. (If it is an HTML or
426 LaTeX specific problem then send that file instead.)
427 </pre>
428 <hr>
429 </BODY>
431 </HTML>