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.

A much more extensive 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.

Probably only useful for historical interest is a web page that describes how cxref was used with the Linux kernel source code many years ago.

Version Status

The latest released version available is version 1.6e.

Recent Changes

The most recent changes in version 1.6e are listed below.

Bug Fixes:

Don't package up unused LSM and ANNOUNCE files.
Pass the CPPFLAGS through to the C compiler (patch from Debian bug #665202).
Don't crash on invalid CPP options (fixes Debian bug #715771).
Handle the special filename that gcc-4.x uses.
Don't crash on unparseable function declaration ("fixes" Debian bug #667443).
Don't report line number 0 for structures/unions defined within other ones.
Make the HTML 4.01 output use the strict DTD rather than the transitional one.
Handle the gcc _Pragma(...) compiler directives.
Allow gcc 4.8 to be used instead of cxref-cpp (ignore internal #defines).

The full version history is in the NEWS file.

Full History

Version 1.6e of cxref released on Wed Jan 22 2014
Version 1.6d of cxref released on Mon Oct 3 2011
Version 1.6c of cxref released on Mon May 31 2010
Version 1.6b of cxref released on Fri Feb 16 2007
Version 1.6a of cxref released on Sun May 1 2005
Version 1.6 of cxref released on Sun Sep 26 2004

Version 1.5g of cxref released on Sat Feb 14 2004
Version 1.5f of cxref released on Sat Feb 14 2004
Version 1.5e of cxref released on Sun June 29 2003
Version 1.5d of cxref released on Sun May 5 2002
Version 1.5c of cxref released on Sat Apr 28 2001
Version 1.5b of cxref released on Sun Sep 26 1999
Version 1.5a of cxref released on Fri Jun 18 1999
Version 1.5 of cxref released on Sun Feb 21 1999
Version 1.4b of cxref released on Sat Apr 18 1998
Version 1.4a of cxref released on Thu Nov 20 1997
Version 1.4 of cxref released on Sat Jul 5 1997
Version 1.3 of cxref released on Sun Dec 8 1996

Version 1.2b of cxref released on Sun Oct 5 1996
Version 1.2a of cxref released on Sat Aug 17 1996
Version 1.2 of cxref released on Sat Jul 6 1996
Version 1.1 of cxref released on Wed May 22 1996
Version 1.0 of cxref released on Sat Feb 24 1996

Download

The source code for the versions listed above are in the download directory.

Subversion

The complete source code history can be browsed in the Subversion viewer which also has a list of the latest changes.

The source code can be downloaded from the Subversion repository with a command like the following:

svn co http://gedanken.org.uk/svn/cxref/trunk cxref

Release Policy

Before the end of 2012 there was a cxref announcement mailing list which was used to announce new versions. The rate of new releases for this software is very low and the complexity of maintaining the mailing list outweighs the benefit. Starting in 2013 the mailing list has been disabled; no new subscriptions are accepted and no further e-mails will be sent to ex-subscribers.

Starting in 2013 there will be two types of software releases (if needed):

Formal releases which are the traditional method used for this software with version numbers like 1.6e. These will continue to be released when there are major changes or important bug fixes and each release includes full updates for release documentation. For these releases announcements will be made on this web page and with a new file in the download directory which includes an RSS feed for notification of new files.

Informal, intermediate, releases which have not previously been used for this software and will have version numbers like 1.6d-svnxyz. These will be used for small bug fixes or minor improvements to functionality. For these releases there will only be the software and directly related documentation changes, not a complete release documentation update. These informal versions will only be available from the download directory and included in the RSS feed found there.

Starting in 2014 there is direct access to the Subversion repository which should remove the need for any intermediate release versions.

Feedback

I am happy to answer questions that you have about the program. Please just drop me an email to the address at the bottom of the page; don't forget to put cxref in the subject so that it ends up in the right mailbox.