Generating API doc with gjdoc/libxmlj and gcj

[Mark Wielaard]

Hi,

Before creating the actual 0.07 release I wanted to make sure that we
could generate API documentation. This is disabled by default since
creating a working gjdoc is non-trivial and the generation of a full
tree takes more then one and half hour (at least on my 1.4 Ghz Athlon)
and takes 150+ MB of memory. At least 25MB of tmp storage and at least
twice so much in your obj build dir.

Since this took (again) much more time then it should have I want to
make sure that I write down the steps that I had to do to make it work
again.

You need gcj 3.3.2 (or higher).
gjdoc CVS :pserver:address@hidden:/cvsroot/cp-tools
module gjdoc.
libxmlj CVS :pserver:address@hidden:/cvsroot/classpathx
module libxmlj.

libxmlj should compile and install out of the box by typing:
make && make install

For gjdoc add at the start of gnu/classpath/tools/gjdoc/Main.java
(main):

  System.setProperty("javax.xml.transform.TransformerFactory",
            "gnu.xml.libxmlj.transform.TransformerFactoryImpl");

There is a ant build.xml file, but I compiled it all by hand together
with the external/jaxp/source files from Classpath which I just copied
in the src direcrory as follows:

  find * -name \*.java | xargs gcj -O2 -g -o gjdoc \
  --main=gnu.classpath.tools.gjdoc.Main

Then I created a simple gjdoc script and put it on my PATH:

  #!/bin/sh
  CLASSPATH=/home/mark/src/libxmlj:/home/mark/src/gjdoc/src/resources \
  LD_LIBRARY_PATH=/usr/local/libxmlj/lib \
  /home/mark/src/gjdoc/src/gjdoc $*

Now you can configure classpah with --enable-gjdoc.
Then typing make and go get yourself some coffe, take a shower and do
some work in the garden.

There is one catch. The above setup is completely broken for some HTML
entities (see [bugs #4823] HTML entities such as auml and nbsp should be
put back in the API doc). So if you have  spectacular and mysterious
crashes then make sure that your java source files don't contain such
entities (for 0.07 I have taken them out).

Cheers,

Mark

signature.asc
Description: This is a digitally signed message part