Distribution

cdoc is distributed as a set of separately downloadable archives:

Prerequisites

My environ.jar package must be in the class path and readable. cdoc will not run without it in the classpath.

environ.jar is supplied as a standalone jar file: use the copy alongside the cdoc jar file in the Sourceforge release directory. This should be downloaded at the same time as you download cdoc. Include this jar file on your CLASSPATH.

If you want documentation for this package, download environ-docs.zip into a suitable empty directory and unzip it. As the documentation is not enclosed in an internal directory, its files will occupy the directory you unzipped it in. After unpacking, point a web browser at the index.html file to read the documentation.

If you want to compile environ.jar yourself, download the environ-srce.zip archive and unzip it. This will create the top-level org directory and unpack the source tree into it, leaving you with the org/gregorie directory structure, which has the Class source files in the environ and image directories. This corresponds to the names of the org.gregorie.environ and org.gregorie.image packages that make up environ.jar. These should all build easily because they do not depend on anything except the standard J2SE class library.

If you want to compile cdoc from scratch, you must download the Coco/R Compiler Generator from www.ssw.uni-linz.ac.at/Research/Projects/Coco/ and install it. It is a single jar file, coco.jar, which must be on your class path when cdoc is being compiled.

Coco/R uses the language definitions in ConditionalExpression.atg to generate Java source for the Parser and Scanner classes. cdoc uses them to parse C source files and the interpret the preprocessor statements they contain.

Building cdoc

Unzip the sources. Find and inspect the Makefile, find the variables JLIB and JLIB2 in it and change them to suit your system. On my system JLIB is a repository for self-developed jarfiles but is not included in $CLASSPATH, while JLIB2 contains all the self-developed and third-party jarfiles on my system. These are all included in $CLASSPATH.

Now change your reference point into the resulting directory containing the Cdoc source files and run

$ make all docs

which should run Coco/R to generate the Scanner and Parser sources, compile all classes and generate cdoc documentation as a set of javadoc web pages.

If you want to test the result you must have also unzipped cdoc-tests.zip. The command:

$ make tests

check compiles the set of C test sources and a set of Java test harnesses used to exercise cdoc's parser classes. With this archive installed you can test cdoc by running the command:

$ java cdoc *.h

which will document all the C test sources, leaving the result in the main directory as a set of HTML files.

Installation and clean-up

Install cdoc by running:

$ make install 

as root. cdoc documentation can be made generally available by moving all the files and directories in docs to a suitable place where it is available to your web browser or your web server. Access the documentation by pointing the browser or web server at index.html

Tidy up by running:

$ make clean

which removes all compiler output and generated documentation.

User manual

The contents of docs/cdoc.html fully describes the use of cdoc.

Incorporating cdoc into a project

cdoc can be run from a makefile after it has been installed. Adding the following to the project makefile will do the job:

CDOCS = docs
CDOCIDX = $(CDOCS)/index.html

(CDOCIDX): *.[ch]
        cd $(CDOCS); java cdoc -DLINUX ../*.h

This assumes that you use the $CLASSPATH environment variable to enable java to find jarfiles at run time. If you don't use it, you'll need to use the -cp option to reference environ.jar and cdoc.jar.

Version history