The integrated cross-platform development tool for ANSI Common Lisp LispWorks logo

Reporting Bugs

Before reporting a bug, please:

  • Ensure that you have the latest patches installed.
  • Ensure that you have the latest patches loaded. The bug report form includes the version number which includes the loaded patch level (e.g. the last 1 in 6.x.1).
  • Check the Lisp Knowledgebase for information about the problem - we may already have fixed it or found workarounds.
  • Read the rest of this page.

 

Backtrace

The most important element in a bug report is the backtrace, in cases where an error is signalled. We need to see this backtrace along with a bug report form.

Bug Report Form

If no error is signalled, we still need the bug report form.

In the LispWorks IDE generate the bug report form with the menu command Help > Report Bug.

You can also generate the bug report form in any listener with the command :bug-form, like this:

Error: Error in function foo
1 (abort) Return to level 0.
2 Return to top loop level 0.

Type :b for backtrace, :c <option number> to proceed, or :? for other options

CL-USER 7 : 1 > :bug-form "Error in function foo" :filename "C:/temp/bug.txt"

The bug report form captures details of the OS and Lisp you are running, as well as the backtrace if your Lisp is in the debugger. There will be delays if you do not provide this essential information.

Problem Description

In the 'Description' field of the bug report form tell us whether or not the bug is repeatable. Add instructions on how to reproduce the bug.

As well as the backtrace, 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).

If you have other data that might help us to identify the problem, such as trace output, include that too. Please do not edit such output, just send it as-is. Where the output is very large and repetitive, the first and last 200 lines might be adequate.

Urgency

In the 'Urgency' field of the bug report form 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.

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:
    for Windows users, in a MS-DOS command prompt window:
    C:\Program Files\LispWorks> lispworks-6-1-0-x86-win32.exe -init init.lisp > lw.out
    or for Mac OS X users, in a Terminal.app window:
    % "/Applications/LispWorks 6.1/LispWorks.app/Contents/MacOS/lispworks-6-1-0-macos-universal" -init init.lisp > lw.out
    or for Linux/Solaris/FreeBSD/Unix users:
    % lispworks -init init.lisp > lw.out
    where lispworks is lispworks-6-1-0-x86-linux or lispworks-6-1-0-x86-freebsd or lispworks-6-1-0-amd64-solaris etc, as appropriate.
  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 and repetitive, the first and last 200 lines might be adequate.

Performance Issues

If the problem is poor performance, you should use room, extended-time and profile to check what actually happens, and attach the output to your report.

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.

Compiler problems

If the problem seems to be compiler-related, set *compiler-break-on-error* to t, and try to repeat it. If this causes the debugger to be entered, be sure to include the backtrace in your report.

Bugs in Delivered Images

First check whether the bug occurs also in the LispWorks development image with your application code loaded. If so, report it as described above.

If the bug occurs only in the delivered image, check that your delivery script calls (load-all-patches). If the image contains the debugger, report it as described above.

If the bug only occurs in a delivered image which does not contain the debugger, try collecting the output as described above.

To pinpoint 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 documentation for details). However, please note that you are not expected to need to add more than 6 or so delivery keywords, so do contact us if you are adding more than this.

When reporting a bug in a delivered image, include the delivery script with your report.

And Finally...

Do not forget the backtrace and bug report form - these are required elements of your report.

Please inform Lisp Support in advance if you need to send us very large files (including Lisp images).

Please note that you need to have a support contract in order to receive support for our Lisp products.

If you need new functionality or have other suggestions for improvements to our products, please send e-mail to .

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.

Top | Back