Re: JSwat cannot find the JPDA
Nathan Fiedler <[email protected]>
| Newsgroups | gmane.comp.java.jswat.user |
|---|---|
| Message-ID | <1034398897.1566.29.camel@chip> |
You're absolutely right. This was entirely my fault. I am very sorry for the wasted time and effort you went through. Your message has been extremely helpful. I have made changes to the README that I hope will address your concerns. I've attached it for your review. Please do read it and let me know what you think. n P.S. Sorry you're getting this more than once. Email troubles... On Fri, 2002-10-11 at 05:58, Christopher Cobb wrote: > Nathan Fiedler wrote: > > > Sure I could reformat the README, but I fear that someone even more > > impatient than yourself would skip over the important bits and blame it > > on me. I'm sorry, but this is not my fault. If you had taken the 30 > > seconds required to read the first couple of paragraphs, you would have > > saved yourself a lot of time. > > I don't think I would characterize my behavior as impatient. Someone who is > impatient wouldn't have pursued a solution as far as I did. I actually believed > I was helping your cause. And I still do. > > There were actually /two/ developers looking at the README at the time we > attempted to install it. Neither of us noticed the crucial instructions, > probably because we both expected salient information to be highlighted or set > apart in some way: either by being indented or bulleted or otherwise formatted > in some way -- and we were in a hurry. We didn't have all day to read every jot > and tittle of the document. We had a bug we needed to find and we had about > thirty seconds to attempt to install and use your product. If we couldn't easily > get the product working, then we would move on to something else which we knew we > could install and use. > > Although the other developer and I did not have an extended discussion on the > philosophy of education, neither of us noticed the crucial information because of > the way it was formatted: I think we both expected that the surrounding prose > would support, explain and expand on the salient information, but not contain it > to the exclusion of other forms of presentation. You effectively use an HTML > table and indentation to emphasize important bits of information, and I think we > both expected that the most crucial piece of information of all would also be > somehow set apart or highlighted. If it is not excruciatingly obvious how to get > an application running in thirty seconds, then something is wrong. (BTW, I'm a > big fan of Java Web Start because it represents an almost fool-proof method of > distributing, installing and running an application. You should consider it.) > > We gave up after spending several minutes trying to get the application to work > and downloaded and installed another application (IDEA) instead -- and it worked > the first time. I went back later for a second attempt at getting your > application running. And once again I missed the salient information. And I > don't think it is completely my own fault. > > Let me make a suggestion with respect to instructional documentation: > repetition, redundancy or otherwise re-presenting material in more than one way > are excellent means to bring home a point. The fact that neither in your FAQ nor > in your mailing list (e.g., in your response to my message) did you actually > RE-STATE the salient instructions means that you are failing at one of the basic > tenants of good instructional communication: repetition of the important > points. I had to dig /very deep/ into your mailing list before I found a > re-statement of the facts that I was looking for. In this sense, your inability > to repeat and set apart a crucial piece of information outside of a single, > unemphasized, sentence embedded within the prose of your README file is a serious > failure of your documentation. > > However, your non-interest in improving your documentation doesn't completely > surprise me, since most developers, especially open source, are more interested > in technical excellence rather than the excellence of the end-user experience. > > But your refusal to acknowledge the soundness of my suggestion to use > -Djava.ext.dirs instead of modifying the JDK's distribution environment indicates > that technical excellence may not be your ultimate goal. There are two things > going for this approach: (1) it doesn't modify the distribution environment of > the JDK, and (2) it makes it more obvious that there is something special > required to run this application. > > Alas, maybe some day you will see the light. I have made my points as best as I > can. As for now, my good will is coming to an end and I don't think it serves > any purpose to use up any more of your bandwidth. > > cc
README.html
(text/html, 8.5 KB)
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<!-- $Id: $ -->
<head>
<meta name="generator"
content="HTML Tidy for Linux/x86 (vers 1st February 2002), see www.w3.org" />
<title>JSwat README</title>
</head>
<body>
<h1 align="center">JSwat README</h1>
<h2>What is it?</h2>
<p>JSwat is a graphical Java debugger front-end, written for the
Java 2 platform, utilizing the <a
href="http://java.sun.com/products/jpda/">Java Platform Debugger
Architecture</a> (JPDA). The source code is licensed under the <a
href="http://www.gnu.org/copyleft/gpl.html">GNU General Public
License</a>. This program is under constant development, though it
can be considered fairly stable and somewhat feature complete.</p>
<hr noshade="noshade" />
<h2>Requirements</h2>
<h3>JPDA</h3>
<p>JSwat requires the <a href="http://java.sun.com/j2se/">Java 2
Standard Edition</a>, version 1.4 or higher. The Java Platform
Debugger Architecture (JPDA) software, which comes with most, if
not all, modern Java Development Kits (JDKs), is utilized by JSwat
to carry out its debugging activities. The required classes are
typically found in the <code><jdk>/lib/tools.jar</code> file,
and begin with the prefix <code>com.sun.jdi</code> (where JDI
stands for Java Debug Interface). The instructions below will
reference the directory containing this jar file, so if it is
located elsewhere in your system, you must make the appropriate
change to the command used to invoke JSwat.</p>
<h3>Other Libraries</h3>
<p>JSwat includes a couple of additional jar files. They are
referenced by the manifest of JSwat jar file and must be kept in
the same directory as the JSwat jar file. The jar files do not have
to be in your classpath, though it would not hurt if they were.</p>
<h3>Debugging Info</h3>
<p>JSwat, like most Java debuggers, requires that the classes to be
debugged be compiled using the <code>-g</code> flag. In addition,
do not compile the classes with the optimization flags, as that may
hinder debugging.</p>
<hr noshade="noshade" />
<h2>Starting JSwat</h2>
<p>There are several ways to start JSwat, but we will only cover
the simplest of these for now.</p>
<blockquote>
<code>java -Djava.ext.dirs=<JAVA_HOME>\lib -jar
<JSWAT_HOME>\jswat.jar</code>
</blockquote>
<blockquote>
<em>Unix users must replace <code>\</code> with <code>/</code> in
the line above.</em>
</blockquote>
<p>Note that <code>JAVA_HOME</code> is the path to the JDK, while
<code>JSWAT_HOME</code> is the path to the <code>jswat.jar</code>
file. The <code><JAVA_HOME>\lib</code> directory must contain
the <code>tools.jar</code> file in order for JSwat to start. This
file contains the JPDA classes (<code>com.sun.jdi</code>) used by
JSwat.</p>
<h3>Passing Arguments</h3>
<p>As with starting any JVM, you can pass options to the JVM
hosting JSwat. See the JDK documentation concerning the
<code>java</code> command for how this is done.</p>
<p>Additionally, JSwat accepts a string of commands to be executed
as soon as JSwat has completed its startup. These commands are
passed at the end of the command line used to start JSwat. Here are
some examples:</p>
<ul>
<li><code>java ... jswat.jar load -client MyClass arg1
arg2</code></li>
<li><code>java ... jswat.jar attach mymachine:1234</code></li>
<li><code>java ... jswat.jar "load MyClass; stop
MyClass:120; resume"</code></li>
</ul>
<p>Read the help section called "Commands" to learn more
about invoking the various commands.</p>
<h3>Other Ways to Start JSwat</h3>
<ol>
<li>
Put the aforementioned <code>tools.jar</code> file and the
JSwat jar file in your classpath and invoke JSwat like so:
<pre>
java com.bluemarsh.jswat.Main
</pre>
</li>
<li>
Copy or link the <code>tools.jar</code> file to the
<code><JAVA_HOME>/jre/lib/ext</code> directory, then
start JSwat like so:
<pre>
java -jar jswat.jar
</pre>
</li>
</ol>
<hr noshade="noshade" />
<h2>Documentation</h2>
<p>The JSwat documentation is made up primarily of the built-in
help. Help on JSwat commands is accessed using the "help"
command. General help topics are available from the
"Help" menu in JSwat.</p>
<hr noshade="noshade" />
<h2>Stopping JSwat</h2>
<h3>Do not use Ctrl-C to exit!</h3>
<p>Using Ctrl-c to exit a program is generally incorrect. It is
especially incorrect with JSwat. You can expect things to break if
you do this. It must <em>only</em> be used in cases where the JVM
hosting JSwat has frozen.</p>
<p>The correct way to exit JSwat is via either the window close
button, the <code>exit</code> command, or the Exit item in the File
menu.</p>
<hr noshade="noshade" />
<h2>Getting the latest source</h2>
<p>The latest source code can be found in the Subversion repository
at <code>http://www.bluemarsh.com/repos/jswat/trunk</code> using
any web browser, or a Subversion client. See the <a
href="http://www.bluemarsh.com/java/jswat/contrib.html">contributing</a>
page on the JSwat web page for more information about using
Subversion to access the repository.</p>
<hr noshade="noshade" />
<h2>Platform Particulars</h2>
<p>Below are notes concerning particular platforms and what must be
done to make JSwat work correctly on them.</p>
<h3>Mac OS X</h3>
<p>According to a Mac OS X 10.1.5 user, it is necessary to add the
hostname of your machine to the <code>netinfo</code> file.
Otherwise you will see an error about <code>gethostbyname</code>
when launching the debuggee. This is because the JPDA uses sockets
to communicate between JSwat and the debuggee, even when the
debuggee is launched by JSwat.</p>
<h3>Windows</h3>
<p>The JRE, often installed with the JDK, seems to cause more
problems than it solves. If JSwat tells you that the JPDA cannot be
found and you are certain you followed the instructions above
correctly, then chances are the JRE is getting in the way. I
recommend saving yourself time and trouble and removing the JRE
from your system. If you cannot do this, then at least delete or
rename the <code>java.exe</code> and <code>javaw.exe</code> files
in the Windows directory.</p>
<h3>Windows NT and JDK 1.4</h3>
<p>There seems to be a problem with using JDK 1.4 on Windows NT
4.0, relating to the DirectX features. The errors occur in the
method <code>sun.awt.windows.Win32DDRenderer.doFillRectDD</code>.
The solution appears to be quite simple, just add the following
option after <code>java</code> when starting JSwat:
<code>-Dsun.java2d.noddraw=true</code></p>
<hr noshade="noshade" />
<h2>Troubleshooting</h2>
<p>Below are problems you might run into while using JSwat. Each
offers a solution for either resolving or working around the
issue.</p>
<h3>prefs BackingStoreException</h3>
<p>See the "Preferences Do Not Persist" item.</p>
<h3>Upgrading to 2.0 message keeps appearing</h3>
<p>See the "Preferences Do Not Persist" item.</p>
<h3>Preferences Do Not Persist</h3>
<p>If the preferences in JSwat are not persisting, you may see one
of the following symptoms:</p>
<ul>
<li>"Updating to 2.0" dialog always displays at
startup.</li>
<li><code>java.util.prefs.BackingStoreException</code> occurs,
maybe mentioning something about an XML parser, such as
xerces.</li>
</ul>
<p>The cause of the problem seems to be that an alternate XML
parser is in the classpath. This XML parser does not understand how
to handle the JavaSoft Preferences DTD and thus fails to read or
write the Preferences data.</p>
<p>The solution is to run JSwat using the <code>-jar</code> option
to provide a "clean" environment in which to run JSwat.
Alternately, you could clear your classpath of everything except
the JSwat jar file.</p>
<p>Simon Hill pointed out that the 2.1 version of the xerces parser
no longer has the problem described above. If you are using an
older version of this parser, you may want to upgrade.</p>
</body>
</html>