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

[julian at sektor37 dot de]

------- Comment #2 from julian at sektor37 dot de  2005-10-12 16:37 -------
Thanks for your detailed bug report, and sorry for the late follow-up.

Vadim Nasardinov <address@hidden> wrote:
> 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.

Seems like you know exactly why which decisions have been made in the
gjdoc code, huh?

It's not quiet as easy as you make it out to be, though.  For example,
the gcj-compiled gjdoc binary doesn't necessarily have access to the
bytecode of core classes (java.* etc.), but it does have access to
those classes via reflection.

So the reflection approach isn't only here to "avoid honest labor",
but instead serves a specific purpose.

I agree with you that where possible, a bytecode-parsing approach
would be preferrable.  Class loading not only poses a security risk
but wastes resources and might cause an Error to be thrown which would
interrupt the documentation generation process.

However, adding support for a bytecode toolkit will introduce an
additional dependency and yes, it will require "honest labor".

I will address this general issue on the cp-tools-discuss mailing list
in the next days.  Perhaps we can come up with a solution that only
uses reflection for "safe" classes (like those in java.lang), and uses
bytecode inspection in all other cases.

I'd like to add that at any rate, I'm treating this as a minor issue.
Given that gjdoc's main target audience are Free software developers,
it is very likely that the source code or at least the API
documentation for third party libraries is available.  And in this
case using the -sourcepath, -link or -linkexternal facilities is the
recommended way to include the library.

However I agree that it's a convenient option, and in some cases the
only option to include third-party libraries, so I confirm your 
report.


> 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 
>
> [---snip---]
>
>   |   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]);

The right way to do this is obviously a custom ClassLoader.  Of course
the above is a "useless attempt" to accomplish that "feat".  That's
why there is a warning which includes the word "faking".  Faking as 
in "to simulate; feign."

The original assumption was that the wrapper script would intercept
the -classpath option and pass it to the VM instead of to gjdoc, so
that the code path above would never be executed.  This assumption no
longer holds true now that there is a native gjdoc binary.  So yes,
confirmed.  I will try to fix that for the next release.


> In theory, gjdoc should ignore CLASSPATH, but it currently honors
> it.

http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/javadoc.html#classpath
says:

>> As with other tools, if you do not specify -classpath, the Javadoc
>> tool uses the CLASSPATH environment variable, if it is set.


-- 

julian at sektor37 dot de changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Severity|normal                      |minor
             Status|UNCONFIRMED                 |NEW
     Ever Confirmed|0                           |1
           Priority|P2                          |P3
   Last reconfirmed|0000-00-00 00:00:00         |2005-10-12 16:37:48
               date|                            |


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