[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Bug gjdoc/23917] New: gjdoc doesn't handle the -classpath option correc
From: |
vadimn at redhat dot com |
Subject: |
[Bug gjdoc/23917] New: gjdoc doesn't handle the -classpath option correctly |
Date: |
16 Sep 2005 14:39:15 -0000 |
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
- [Bug gjdoc/23917] New: gjdoc doesn't handle the -classpath option correctly,
vadimn at redhat dot com <=