14.10.1 Check for existing fixes

Before reporting a bug, please ensure that you have the latest patches installed and loaded. Visit www.lispworks.com/downloads/patch-selection.html for the latest patch release.

If the bug persists, check the Lisp Knowledgebase at www.lispworks.com/support/ for information about the problem - we may already have fixed it or found workarounds.

If you need informal advice or tips, try joining the LispWorks users' mailing list. Details are at www.lispworks.com/support/lisp-hug.html .

14.10.2 Performance Issues

If the problem is poor performance, you should use room, extended-time and profile to check what actually happens. See the LispWorks User Guide and Reference Manual for details of these diagnostic functions and macros.

If this does not help you to resolve the problem, submit a report to Lisp Support (see next section) and attach the output of the diagnostics.

14.10.3 Generate a bug report template

Whatever method you want to use to contact us, choose Help > Report Bug from any tool, or use the command Meta+X Report Bug, or at a Lisp prompt, use :bug-form, for example:

:bug-form "foo is broken" :filename "bug-report-about-foo.txt"

All three methods produce a report template you can fill in. In the GUI environment we prefer you use the Report Bug command - do this from within the debugger if an error has been signalled.

The bug report template captures details of the Operating System and Lisp you are running, as well as a stack backtrace if your Lisp is in the debugger. There may be delays if you do not provide this essential information.

If the issue you are reporting does not signal an error, or for some other reason you are not able to supply a backtrace, we still want to see the bug report template generated from the relevant LispWorks image.

14.10.4 Add details to your bug report

Under 'Urgency' tell us how urgent the issue is for you. We classify reports as follows:

ASAP

A bug or missing feature that is stopping progress. Probably needs a private patch, possibly under a support contract, unless a workaround can be found.

Current Release

Either a fix in the next patch bundle or as a private patch, possibly under a support contract.

Next Release

A fix would be nice in the next minor release.

Future Release

An item for our wishlist.

None

Probably not a bug or feature request.

Tell us if the bug is repeatable. Add instructions on how to reproduce it to the 'Description' field of the bug report form.

Include any other information you think might be relevant. This might be your code which triggers the bug. In this case, please send us a self-contained piece of code which demonstrates the problem (this is much more useful than code fragments).

Include the output of the Lisp image. In general it is not useful to edit the output, so please send it as-is. Where output files are very large (> 2MB) and repetitive, the first and last 200 lines might be adequate.

If the problem depends on a source or resource file, please include that file with the bug report.

If the bug report falls into one of the categories below, please also include the results of a backtrace after carrying out the extra steps requested:

• If the problem seems to be compiler-related, set *compiler-break-on-error* to t, and try again.
• If the problem seems to be related to error or conditions or related functionality, trace error and conditions:coerce-to-condition, and try again.
• If the problem is in the LispWorks IDE, and you are receiving too many notifiers, set dbg:*full-windowing-debugging* to nil and try again. This will cause the console version of debugger to be used instead.
• If the problem occurs when compiling or loading a large system, call (toggle-source-debugging nil) and try again.
• If you ever receive any unexpected terminal output starting with the characters <**>, please send all of the output--however much there is of it.

Note: terminal output is that written to *terminal-io*. Normally this is not visible when running the Mac OS X native GUI or the Windows GUI, though it is displayed in a Terminal.app or MS-DOS window if necessary.

14.10.5 Reporting crashes

Very occasionally, there are circumstances where it is not possible to generate a bug report form from the running Lisp which has the bug. For example, a delivered image may lack the debugger, or the bug may cause lisp to crash completely. In such circumstances:

1. It is still useful for us to see a bug report form from your lisp image so that we can see your system details. Generate the form before your code is loaded or a broken call is made, and attach it to your report.
2. Create a file init.lisp which loads your code that leads to the crash.
3. Run LispWorks with init.lisp as the initialization file and with output redirected to a file. For example, on Mac OS X:
% "/Applications/LispWorks 7.1 (32-bit)/LispWorks (32-bit).app/Contents/MacOS/lispworks-7-1-0-x86-darwin" -init init.lisp > lw.out

where % denotes a Unix shell prompt.

On Windows:

C:\> "Program Files\LispWorks\lispworks-7-1-0-x86-win32.exe" -init init.lisp > lw.out

where C:\> denotes the prompt in a MS-DOS command window.

On Linux:

% /usr/bin/lispworks-7-1-0-x86-linux -init init.lisp > lw.out

where % denotes a Unix shell prompt.

On UNIX (SPARC in this example):

% /usr/lib/lispworks/lib/7-1-0-0/config/lispworks- 7-1-0 -sparc-solaris -init init.lisp > lw.out
4. Attach the lw.out file to your report. In general it is not useful to edit the output of your Lisp image, so please send it as-is. Where output files are very large (> 2MB) and repetitive, the first and last 200 lines might be adequate.

14.10.6 Log Files

If your application writes a log file, add this to your report. If your application does not write a log file, consider adding it, since a log is always useful. The log should record what the program is doing, and include the output of (room) periodically, say every five minutes.

You can make the application write a bug form to a log file automatically by making your error handlers call dbg:log-bug-form.

14.10.7 Reporting bugs in delivered images

Some delivered executables lack the debugger. It is still useful for us to see a bug report template from your Lisp image that was used to build the delivered executable. If possible, load your code and call (require "delivery") then generate the template.

For bugs in delivered LispWorks images, the best approach is to start with a very simple call to deliver, at level 0 and with the minimum of delivery keywords (:interface :capi and :multiprocessing t at most). Then deliver at increasingly severe levels. Add delivery keywords to address specific problems you find (see the LispWorks Delivery User Guide .for details. However, please note that you are not expected to need to add more than 6 or so delivery keywords: do contact us if you are adding more than this.)

14.10.8 Send the bug report

Email is usually the best way. Send your report to

lisp-support@lispworks.com

When we receive a bug report, we will send an automated acknowledgment, and the bug will be entered into the LispWorks bug management system. The automated reply has a subject line containing for example

(Lisp Support Call #12345)

Please be sure to include that cookie in the subject line of all subsequent messages concerning your report, to allow Lisp Support to track it.

If you cannot use email, please either:

• Fax to +44 870 2206189
• Post to Lisp Support, LispWorks Ltd, St John's Innovation Centre, Cowley Road, Cambridge, CB4 0WS, England
• Telephone: +44 1223 421860

Note: It is very important that you include a stack backtrace in your bug report wherever applicable. See Generate a bug report template for details. You can always get a backtrace from within the debugger by entering :bb at the debugger prompt

14.10.9 Sending large files

Note: Please check with Lisp Support in advance if you are intending to send very large (> 2MB) files via email.

14.10.10 Information for Personal Edition users

We appreciate feedback from users of LispWorks Personal Edition, and often we are able to provide advice or workarounds if you run into problems. However please bear in mind that this free product is unsupported. For informal advice and tips, try joining the LispWorks users mailing list. Details are at www.lispworks.com/support/lisp-hug.html .