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.
In SLIME, generate the bug report form from the sldb
buffer by using the :
[colon] command to call (dbg:output-backtrace :bug-form)
. The output will appear in the slime-repl.
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:
- 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.
- Create a file
init.lisp
which loads your code that leads to the crash. - 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 (x86)\LispWorks> lispworks-8-0-0-x86-win32.exe -init %TEMP%\init.lisp > %TEMP%\lw.out
- or for macOS users, in a Terminal.app window:
% "/Applications/LispWorks 8.0 (64-bit)/LispWorks (64-bit).app/Contents/MacOS/lispworks-8-0-0-macos64-universal -init /tmp/init.lisp > /tmp/lw.out
- or for Linux/Solaris/FreeBSD users:
% lispworks -init /tmp/init.lisp > /tmp/lw.out
where lispworks islispworks-8-0-0-x86-linux
orlispworks-8-0-0-x86-freebsd
orlispworks-8-0-0-amd64-solaris
etc, as appropriate.
- 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 email your completed bug report form to Lisp Support via .
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 email 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.