The Cxref Homepage

C Cross Referencing & Documenting tool

Cxref is a program that will produce documentation (in LaTeX, HTML, RTF or SGML) including cross-references from C program source code.
It has been designed to work with ANSI C, incorporating K&R, and most popular GNU extensions.

(The cxref program only works for C not C++, I have no plans to produce a C++ version.)

The documentation for the program is produced from comments in the code that are appropriately formatted. The cross referencing comes from the code itself and requires no extra work.

The documentation is produced for each of the following:

Files: A comment that applies to the whole file.
Functions: A comment for the function, including a description of each of the arguments and the return value.
Variables: A comment for each of a group of variables and/or individual variables.
#include: A comment for each included file.
#define: A comment for each pre-processor symbol definition, and for macro arguments.
Type definitions: A comment for each defined type and for each element of a structure or union type.

Any or all of these comments can be present in suitable places in the source code.
As an example, the file README.c has been put through cxref to give HTML output.

The cross referencing is performed for the following items

Files
- The files that the current file is included in (even when included via other files).
#includes
- Files included in the current file.
- Files included by these files etc.
Variables
- The location of the definition of external variables.
- The files that have visibility of global variables.
- The files / functions that use the variable.
Functions
- The file that the function is prototyped in.
- The functions that the function calls.
- The functions that call the function.
- The files and functions that reference the function.
- The variables that are used in the function.

Each of these items is cross referenced in the output.

Detailed Information

The program comes with more detailed information. There is a README, which contains an example of the output of the program. (also available in PostScript or plaintext.)

A fuller example of the output of the program can be seen in the cxref output for the cxref source code itself.

These pages were generated by using the cxref command on each source file using the following command line (for cxref.c):

cxref -Oexample -Ncxref -html-src cxref.c

The same command line format was used for each file in turn and the whole set of commands run twice to first collect cross references then produce the output. The full set of output was generated by running make docs on the cxref source code.

To help with problems encountered in using the program, there is a FAQ. Cxref (in various versions) has been tested on the following systems: Linux 1.[123].x, Linux 2.[01234].x, SunOS 4.1.x, Solaris 2.x, HPUX 10.x, AIX, Irix, (Free|Net)BSD, Win32 with Cygnus development kit.

Version Status

The latest released version available is version 1.6a.

Version 1.6b of cxref released Fri Feb 16 09:00:00 2007

Bug fixes
 Define a value for PATH_MAX in case one is not already defined.
 Fix scope problem with declarations of pointers to functions.
 Remove some compilation warnings with gcc 4.

Version 1.6a of cxref released Sun May 1 16:30:00 2005

Bug fixes
 Added function prototypes to allow cxref-cpp to work on 64-bit machines.
 Fix bug reading from freed memory and small memory leak.
 Stop comments intended for functions appearing on #defines inside function.
 If cxref-cpp cannot find include directory from cxref-cpp.defines then abort.
 Fix installation of manual page.

Parsing changes
 Allow variable declaration in for(;;) statements.
 Allow named initialisation of structure/union using named initialisers.
 Fix bad handling of some vararg macros in cxref-cpp.

Version 1.6 of cxref released Sun Sep 26 2004

Bug fixes
 Remove unwanted </a> tag in HTML output for some variables.
 Added C99 Complex and Boolean types
 Handle a goto statement or a named label with a type name.
 Stop a structure pointer to function looking like a function declaration.

cxref-cpp changes
 Now uses gcc-2.95.3 as the base for the pre-processor.

Configure/Make changes
 Fix compilation outside of the source tree (except for example cxref docs).
 Change the directory layout by moving the source into src and READMEs into doc.

Output changes
 Removed the -html20 and -html32 options, the -html output is now version 4.01.
 Removed the -latex209 and -latex2e options, the -latex output is version 2e.
 HTML option generates a cxref stylesheet and uses it.

Version 1.5g of cxref released Sat Feb 14 2004
Version 1.5f of cxref released Sat Feb 14 2004
Version 1.5e of cxref released Sun June 29 2003
Version 1.5d of cxref released Sun May 5 2002
Version 1.5c of cxref released Sat Apr 28 2001
Version 1.5b of cxref released Sun Sep 26 1999
Version 1.5a of cxref released Fri Jun 18 1999
Version 1.5 of cxref released Sun Feb 21 1999

Version 1.4b of cxref released Sat Apr 18 1998
Version 1.4a of cxref released Thu Nov 20 1997
Version 1.4 of cxref released Sat Jul 5 1997

Version 1.3 of cxref released Sun Dec 8 1996

Version 1.2b of cxref released Sun Oct 5 1996
Version 1.2a of cxref released Sat Aug 17 1996
Version 1.2 of cxref released Sat Jul 6 1996

Version 1.1 of cxref released Wed May 22 1996
Version 1.0 of cxref released Sat Feb 24 1996

The full version history is in the NEWS file distributed with the program.

Mailing List

There is a mailing list available for announcements about new versions of Cxref. This will only be used by me to send announcements about new versions of Cxref, it is not for Cxref discussions.

To subscribe to this list send an e-mail to cxref-announce-request "at" gedanken.demon.co.uk with subscribe in the body.

Download

Source Code

Cxref version 1.6b source code and patches can be downloaded from this server:

The complete version 1.6b source code: cxref-1.6b.tgz [388 kB]

The patch from version 1.6a to 1.6b: cxref-1.6a-1.6b.diff.gz [114 kB]
The patch from version 1.6 to 1.6a: cxref-1.6-1.6a.diff.gz [11 kB]

The download directory also contains PGP Signatures for the files using my PGP Key.

Other Packages

Some Linux distributions contain cxref and there are packages for some other operating systems (incomplete list below).
If you have problems using these packages refer to the package producer in the first instance.

Debian Linux Packages (Maintained by Camm Maguire <camm "at" enhanced.com>).
Ubuntu Linux Packages search results.
NetBSD Packages.
FreeBSD Packages.
Mac OS X Package.

Feedback

I am happy to answer questions that you have about the program. Please just drop me an email to <amb "at" gedanken.demon.co.uk> don't forget to put cxref in the subject so that it ends up in the right mailbox.