So you think you've found a bug?

Well, ya know what... we're all just human, and compilers for any language are very difficult beasties to write so you may very well have done just that. Here's what we need you to do in order to correct this problem, without your help the odds of this bug being fixed are infinitesimally small.

Overview of process from here:

1. Verify that this isn't a WKB (Well Known Bug) aka an FRB (Frequently Reported Bug).
2. Verify that this is in fact a Jikes bug.
3. Check that this bug is not already reported.
4. Collect the information needed for a Jikes bug report.
5. Report the bug.
6. Assist in the elimination of the bug.
7. Verify the bug has been fixed.

Verify that this isn't a WKB

Anytime we have a brown paper bag incident it will be listed here, if your bug is listed here and you still report it, expect to be ignored unless you have some new information; in which case you should append your information to the existing bug. (Please don't append "me too, you should fix this" type of messages.) Current status is indicated thusly.

Empty if clause in if-else statement causes problems

This is bug . In Jikes 1.16, if the if clause of an if-else statement is empty, the else clause is not compiled correctly. The workaround is to ensure there is a statement in the if clause, even if it does nothing. Fixed in CVS.

Classpath crashes

Older Jikes builds (~1.06 - 1.11) would occasionally drop core due to the length of the classpath (not so much that it was too long, as that it was "oddly mod 2" long), this also varied based on the platform and how its compiler laid out memory -- an excellent example of what happens when you trample on someone else's memory in C++ ;). FIXED in 1.12 (partially) and 1.13 (completely?).

Parser

The parser is responsible for converting your source code into the Abstract Symbol Tree that the compiler uses internally to produce classes. Errors such as not recognizing a method name, or not seeing that a block could throw a certain type of exception would belong to the parser.

Emitter

The emitter is responsible for turning the AST produced by the parser into bytecode in class files. Errors such as not emitting a branch argument that would lead outside the method, or any other bytecode that would cause a class file to fail verification would belong to the emitter.

Dependencies

The dependency subsystem is responsible for tracking what classes make use of what other classes. A bug against the dependency tracker might be if a class should have been recompiled because other classes changed, but it wasn't.

User Interface

The user interface is responsible for dealing with command line options, and reading user environment variables, an example bug against the UI is that the usage test ignores the -Xstdout argument and prints to stderr.

Build

Use the build component if the Jikes source code fails to compile on your platform, examples include faulty logic in ./configure tests.

Specifications

This component is used to track Jikes' compliance with specification issues, and more often to track when clarification is needed from Sun.

Documentation / Web

This component is used report problems either in the website, or the shipped documentation. For example, if a link goes 404.

Suggestion or Feature Request

This one should be self-explanatory, RFEs go here.

If you do find your bug in one of the above categories already then you should evaluate if you have any additional information you can add to the existing bug, such as a simpler testcase, or a backtrace of a core fault or assertion. See the next section for some of the common information we need to properly deal with a bug, if the original report doesn't contain some of that info, can you supply it? If so please append it to the existing bug. If, on the other hand, you do not see your bug in any of the existing ones, please continue to the next step and collect the information needed for your new bug.

Collect the information needed for a Jikes bug report

There are some basic pieces of information that are needed for a bug report, surprisingly a number of bugs come it that lack this basic information. I say this is surprising because of the target audience of the project... developers. You're a Java developer right, how would you like a defect from your users that just says: "it dumped core, you should fix it"?

All bug reports must include the following basic information:

Version

What version of Jikes have you recreated the problem with, is it the most currently released version? If not retest with that version before submitting your bug. (If you don't you'll be asked to do so before anyone really looks at the bug.) If you're building it from CVS when did you last do a CVS update? Do you have any diffs against the current CVS tree? (Intentionally or not.)

Platform

What kind of machine are you on? What's the operating system? The C/C++ library? What's the version? If we don't know what you're running on we can't tell you if it's a known issue on that platform, or possibly recreate it if it's a previously unknown quirk.

Full Error Message

What was the full error message? Did Jikes leave a file called core in the directory you ran it from? Did Jikes abort? What was the assertion that lead to the abort? If you're using a Unix-like operating system and Jikes crashed, follow the steps below for collecting useful information after crashes. (For those on Windows, you'll have to rely on Dr. Watson or Quincy to see what the stack trace is, sorry.)

Testcase

We have to know how to recreate the problem in order to debug it. Testcases should preferably be in jacks format; however, this is not a hard and fast rule. Testcases must however be COMPLETE and SELF-CONTAINED. Testcases should also include an example of how to use it... even if it seems obvious; we've had bugs returned as "works for me" because the submitter neglected to mention that the problem only happens with the -g option passed to the compiler. Defects without testcases will most likely not be looked at by any of the main developers, if they are, resulting patches are near impossible to get into the main tree without a regression test, which usually comes from the initial bugs' testcase.

Contact information

This one sometimes strikes people as odd... but bug reporting is not a one-way street. If you're going to take the time to report a bug, and we're going to take the time to fix the bug, then we need a way to communicate with you it's as simple as that. The new dW/osssf system we use to collect bugs has one advantage... you can't submit a bug without verifiable contact information.

Gathering useful information after a crash

If Jikes crashes, it's best if you can provide a small test case that repeatably causes Jikes to crash. Doing this gives you the best chance of having the bug fixed.

If you can't come up with a small repeatable test case, we'll want a stack trace. When a C++ program such as Jikes crashes, you don't automatically get a stack trace as you would with Java. Here are the steps for collecting a stack trace:

1. Download and unpack the Jikes source.
2. ./configure --enable-debug
3. make
4. Unset any limits on core dump size, usually with the command ulimit -c unlimited
5. Use the resulting build untill it falls over. This should leave you with a file called core, usually in the current directory but in /cores on Mac OS X (where all cores are numbered).
6. Capture the output when it dies, especially any assertion messages that appear right at the end.
7. Use gdb to get a stack trace of the failure. You run gdb like this: gdb /path/to/jikes /path/to/core. The only two commands you need are bt (backtrace) and quit.

You can use the information from steps 6 and 7 to look at the existing bugs for any similar ones, or open a new one. Sometimes knowing where it died will help in writing a smaller test case that you can post in your bug report. Looking at the stack traces can also help you recognize if you're hitting the same problem over and over, or if you keep finding new ones (and crashing in very different places).

Report the bug

This is the easy part. Just go to the submission page and put all the information above into the form in some nice coherent fashion. The first thing you'll need to supply is your email address, be sure to put a VALID address, you'll also need to decide if you want this address to be publicly visible on this bug. Reference the IBM Privacy Guidelines at the bottom of that page for details, but the general gist of this switch is that the dW staff, and (in theory) the Jikes project administraitors and registered developers will be able to see your address either way (although this is currently broken such that only the deverloperWorks staff can retrieve all addresses) but the general public will ONLY be able to see your address if you check the box. Note that this is the address where the system will mail updates about the status of your bug as it changes. The next option you need to provide is what category your bug belongs in. Reference the set of categories above for details, or leave it as None if you don't know. The bug group can be left alone or set to Open. Next you will need to furnish a short summary of the problem... this is limited to a couple dozen characters, so be breif but CLEAR. That last large area... well that's where everything else goes.

After you click submit there is one last very important step you'll have to do: confirm your address. A message will be sent to your email address which contains a URL... until you visit that URL your bug will NOT be seen, you must visit the URL that is sent to you in order to confirm your address is valid.

Assist in the elimination of the bug

Having reported the bug many people think that their job is finished, ideally this maybe the case, but out here in the real world it never is. As developers and other users are working on your bug they may need information, they'll post questions, or suggestions to work around the bug into it's record in the database. If we never hear from you again then odds are very good that the bug will never move forward. You have got to stick around a help with the debug process.

Verify the bug has been fixed

The last step. By now the bug has been cornerd and eradicated, a patch has been developed, and commited, possibly even shipped. This last step is the most important from your end... verify that the fix works on your machine, with your project in your environment. This can be especially important with bugs where you had to reduce any enviroment of input inorder to produce a testcase. Once a bug is verified as fixed either in a cvs build or in an official production release.