[Bug gjdoc/23917] New: gjdoc doesn't handle the -classpath option correctly

[vadimn at redhat dot com]

gjdoc 0.7.5 that ships with Fedora Core 4 doesn't handle the
-classpath option correctly.  I haven't tried the latest CVS version.
Apologies if this has been fixed already.  (I did look at today's
checkout of gjdoc/ChangeLog and didn't notice anything that would
suggest this had been addressed already.)

| $ cat /etc/fedora-release
| Fedora Core release 4 (Stentz)
| $ rpm -qf $(which gjdoc)
| gjdoc-0.7.5-3

Java source files may reference classes supplied by third-party
libraries.  For gjdoc to resolve these references, it has to be able
to find said third-party jars.  In theory, their location is specified
via the -classpath option.  Upon encountering a reference to a class
for which there is no source in the current sourcepath, gjdoc should
look inside the jars listed in the -classpath option, find the
referenced .class files, and parse its bytecode in order to extract
the information needed by gjdoc (superclasses, inherited methods, and
suchlike).

In practice, there is a number of issues with the handling of the
-classpath option in gjdoc.  I'm attaching a test case that
demonstrates the issues.  The contents of the test case are:

| $ find . -type f -printf '%P\n'
| Makefile
| 3rd-party/third/party/lib/Quux.java
| src/my/source/Foo.java

Quux.java is compiled and packaged as third-party.jar to simulate a
sloppily written and/or malicious third-party library.  Foo.java is a
class for which we are trying to generate javadoc with gjdoc.  Foo
extends Quux.

Here's the list of issues:

1. gjdoc tries to pass the value of the -classpath option to the JVM
   in which gjdoc itself is running.  It attempts this feat by doing
   the following

   | $ cvs status src/gnu/classpath/tools/gjdoc/Main.java | grep Working
   |    Working revision:    1.74
   | $ cat -n src/gnu/classpath/tools/gjdoc/Main.java | head -n1476 | tail -n9
   |   1468      options.put("-classpath", new OptionProcessor(2)
   |   1469        {
   |   1470          void process(String[] args)
   |   1471          {
   |   1472            reporter.printWarning("-classpath option could not be 
passed to the VM.  Faking it with ");
   |   1473            reporter.printWarning("    
System.setProperty(\"java.class.path\", \"" + args[0] + "\");");
   |   1474            System.setProperty("java.class.path", args[0]);
   |   1475          }
   |   1476        });

   By the time the JVM is up and running, changing the
   "java.class.path" doesn't do any good.  AFAIK, it's a read-only
   property.  (You can change it, but that doesn't have any effect on
   the system classpath.)

   The effects of trying to set the -classpath flag can be seen by
   running the "doc1" target in the attached test case:

   | $ make doc1
   | mkdir -p build/{classes,jar}
   | gcj -C -d build/classes 3rd-party/third/party/lib/Quux.java
   | jar cf build/jar/third-party.jar -C build/classes .
   | mkdir -p build/doc1
   | gjdoc -d build/doc1 -classpath build/jar/third-party.jar -sourcepath src 
my.source
   | WARNING: -classpath option could not be passed to the VM.  Faking it with
   | WARNING:     System.setProperty("java.class.path", 
"build/jar/third-party.jar");
   | Loading classes for package my.source...
   | Constructing Javadoc information...
   | WARNING: Error while loading class Quux
   | WARNING: Cannot locate class third.party.lib.Quux referenced in class 
my.source.Foo
   | Resolving references in comments...
   | Resolving references in classes...
   | Resolving references in packages...
   | Resolving references in class comments...
   | Resolving references in package comments...
   | Running doclet...
   | Building cross-reference information...
   | Writing overview files...
   | Writing index...
   | Writing HTML files for package my.source
   | 4 warnings

2. The reason why gjdoc tries to set the system classpath to the value
   specified in the -classpath option is so that it can avoid the
   honest labor of bytecode parsing by leveraging reflection instead.

   By default, it doesn't use reflection however.  This can be seen by
   running "make doc2".  In this case, we work around the '-classpath'
   uselessness by setting the environment variable CLASSPATH instead.
   (In theory, gjdoc should ignore CLASSPATH, but it currently honors
   it.  Does this merit a ticket of its own?)

   | $ make doc2
   | mkdir -p build/doc2
   | export CLASSPATH=build/jar/third-party.jar && gjdoc -d build/doc2 
-sourcepath src my.source
   | Loading classes for package my.source...
   | Constructing Javadoc information...
   | WARNING: Error while loading class Quux
   | WARNING: Cannot locate class third.party.lib.Quux referenced in class 
my.source.Foo
   | Resolving references in comments...
   | Resolving references in classes...
   | Resolving references in packages...
   | Resolving references in class comments...
   | Resolving references in package comments...
   | Running doclet...
   | Building cross-reference information...
   | Writing overview files...
   | Writing index...
   | Writing HTML files for package my.source
   | 2 warnings

3. We can get the Quux reference resolved by telling gjdoc to use
   reflection which is done by passing the gjdoc-specific -reflection
   flag.  This is demonstrated by "make doc3":

   | $ make doc3
   | mkdir -p build/doc3
   | export CLASSPATH=build/jar/third-party.jar && gjdoc -reflection -d 
build/doc3 -sourcepath src my.source
   | Loading classes for package my.source...
   | 
------------------------------------------------------------------------------
   | *********               Harmful side effect in action!               
*********
   | 
------------------------------------------------------------------------------
   | Constructing Javadoc information...
   | WARNING: Cannot locate class third.party.lib.Quux on file system, falling 
back to reflection.
   | Resolving references in comments...
   | Resolving references in classes...
   | Resolving references in packages...
   | Resolving references in class comments...
   | Resolving references in package comments...
   | Running doclet...
   | Building cross-reference information...
   | Writing overview files...
   | Writing index...
   | Writing HTML files for package my.source
   | 1 warnings

   This time around, we are finally able to get semi-correct javadoc
   where Foo is shown to inherit from third.party.lib.Quux.  This is
   accomplished at the expense of running potentially harmful code in
   third-party.jar.  This is because gjdoc ends up running
   Class.forName("third.party.lib.Quux") which executes the static
   initializer of Quux.

   (I say "semi-correct", because it doesn't show methods inherited by
   Foo from Quux.  Should I file a separate ticket for this?)

-- 
           Summary: gjdoc doesn't handle the -classpath option correctly
           Product: classpath
           Version: unspecified
            Status: UNCONFIRMED
          Severity: normal
          Priority: P2
         Component: gjdoc
        AssignedTo: julian at sektor37 dot de
        ReportedBy: vadimn at redhat dot com
                CC: bug-classpath at gnu dot org


http://gcc.gnu.org/bugzilla/show_bug.cgi?id=23917