This document gives general guidelines for reporting bugs in Outgun. Some information here is beneficial to read even before you’ve actually come across a bug.
Reporting bugs as well as possible is not very simple. You can just tell us when something goes wrong, but with bad luck that doesn’t help at all in finding and fixing the actual problem. You can use the advice on this page to get more information afterwards from a bug that happens to be repeatable, but in case you hit a bug that only happens randomly, it helps to prepare in advance.
There are many kinds of bugs, as explained in the section what is a bug. Of those, crashes are the hardest to investigate, since by default almost no useful information is produced. Enabling the information to be produced is not very simple, but you should be able to enable it with these instructions. In the case of Linux you need to know how to use the console to do that.
Assertions are easier to deal with than crashes, and you can help us without going through any trouble by enabling “automatic bug reporting” in Outgun’s options menu. However, you should still report the bug yourself, and not only for the credit. Often the automatic information is not enough without knowing what you were doing when the assertion was triggered. Also, partly because the reporting system is made as simple and unobtrusive as possible, some automatic bug reports don’t reach us even if the feature is enabled. Notice that the automatic bug reports are anonymous and we have no means of asking you for more details, unless you directly contact us about the bug.
Finally, note that reporting bugs properly (or at least at all) is doing a huge favor to the whole Outgun community, rather than just us developers. Most bugs are elusive and occur rarely, so don’t just think someone else will report it if you don’t! We wish to thank all reporters of bugs here, also the anonymous ones who can’t be credited in Outgun’s readme.
This chapter explains how to get an idea about what happened in a crash. This information is crucial for us in order to fix the bug. Here, crash means when Outgun abruptly closes without a message or with a message other than “assertion failed”. In contrast, the assertions produce an useful message and a
log/stackdump.bin, and from other kinds of errors all the useful information is in the logs.
Dr. Watson is a tool built into Windows that extracts necessary information from a program that crashes. When Outgun (or any other program) crashes, it takes a moment while Dr. Watson creates its log file. When reporting a crash, send the latest log file to us. It will often tell us pretty exactly what finally went wrong. (But it doesn’t remove the need to know what you were doing and if some other unexpected thing happened.)
Operating Dr. Watson depends on your Windows version. We only know exactly how to do it on a few Windows platforms. If you manage to run it on another platform according to one of these instructions or somehow else, do tell us and it’ll be included here.
In these older Windowses you must manually start Dr. Watson whenever you use Outgun. You can start it manually by running (Start / Run...) drwatson.exe, or by creating a shortcut to it. To make it automatically start with Windows, add a shortcut to it in your start menu startup group. Whenever it’s running, it will display an icon in the system tray. You can click on it to change its options, but the default ones are good. To make the logs smaller, you can change the “Number of instructions” field to the minimum of 1, but do not reduce the “Number of stack frames” field to much less than 100.
On these Windows versions, by default Dr. Watson saves its logs to
C:\Windows\Drwatson\ or similar. Each crash is usually given its own file, while some crashes may produce many files. In that case, send all the logs from the crash; you can see which ones to send from the file dates.
In newer Windowses, Dr. Watson runs automatically. You can check this by verifying that there are logs in
C:\Documents and Settings\All Users\Application Data\Microsoft\Dr Watson\ (replace “
Application data” with “
Dados de aplicativos” for a Portuguese Windows). If it’s not running, you might try running it by Start / Run... / drwatson.exe. To access Dr. Watson’s settings, go to Start / Programs / Accessories / System Tools / System Information / Tools / Dr Watson. You should configure it to overwrite its old logs (uncheck “Append To Existing Log File”), otherwise you’ll have to periodically delete the old logs manually to avoid sending larger files than needed. You can also reduce the “Number of Instructions” to the minimum to save in log size.
On these Windows versions, by default Dr. Watson saves its log as
C:\Documents and Settings\All Users\Application Data\Microsoft\Dr Watson\drwtsn32.log (replace “
Application data” with “
Dados de aplicativos” for a portuguese Windows). Unless you uncheck “Append To Existing Log File” or periodically delete this file, it contains a whole lot of crash logs and can grow very large.
These Windows versions can be configured to close crashing programs without giving you any visible info. If Outgun crashes this way, you can see from the date of Watson’s log that it was indeed a crash. In that case, do send us the log.
Linux can easily be configured to produce core dumps whenever a program crashes. The dumps contain all the information there is about the crashing program. The problem is, they’re large, and system specific. However, you can extract the most important information out of them in a relatively simple way.
If your system doesn’t produce core dumps by default, you must enable them, usually by executing “ulimit -c unlimited” (bash) or “unlimit coredumpsize” (csh) in the shell you run Outgun from. You can automate this by appending the line to the shell startup script, for example
.bashrc. That way it will affect every application. To only get dumps from Outgun, you should create a script which removes the core dump limit and then executes Outgun, and use this script instead whenever you intend to run Outgun.
Extracting information from the core dump (usually a file whose name starts with
core in the directory in which you run Outgun) happens by running the GNU debugger, gdb. If the core dump is called
core.5636 and resides in the Outgun directory, and that is your current directory, type:
gdb outgun core.5636 bt q
The first command runs gdb telling it to read debugging information about the executable
outgun, and the core dump
bt tells gdb to output a backtrace, which hopefully shows a list of addresses and function names in Outgun. This list you should send to us.
q tells gdb to quit.
To prepare for the hardest-to-solve bugs, it is useful to run Outgun with the command line switch “
2”. That way you will have some more log files that may prove useful in debugging a problem.
The regular logs usually contain some useful clues too, so it is important you don’t remove them after noticing a new bug. Notice that restarting Outgun clears the old logs, so it is best to back up the whole log directory on the event of a bug; otherwise if the bug happens to not be repeatable, all useful information is lost.
Anything that doesn’t feel right, qualifies for reporting as a bug. This includes (but is not necessarily limited to)
In any of these cases, or when something just feels weird, consider reporting. However, don’t report stuff that’s already been reported: check the web page of known issues first (see known issues for Outgun 1.0). There, both bugs and legitimate behavior reported as weird by someone, are listed. Also, avoid reporting something that is probably an issue with your own system – particularly problems that are common with other games.
What you should include in a bug report varies with the kind of bug you’re reporting. Choose from the list below those items that apply to your situation. You don’t have to be formal and write pages of information, but the more you include, the easier it is to find and fix the problem. When you have a problem that happens every time you do a certain thing in a certain way, it is enough to send information about what to do to make it happen. However, if we can’t reproduce it on our computers, we’ll have to ask you for more information from this list.
When you first have a problem, a good procedure for testing if it’s repeatable, is to backup (copy to another directory) the Outgun
log directory, not delete any other log, and then try again. If you can’t repeat it, send the original logs and as much of other information as possible. If you can repeat it, just tell us what to do to repeat it here.
log/log.txttells this information.
sayadmin.logand other unrelated files) will often help.
configdirectory), if appropriate.
Send e-mail to firstname.lastname@example.org with “Bug report” mentioned in the subject. This is easier than ICQ in that you don’t have to wait for us to be online. Attach any files to the message (zipped, rarred or plain), if possible, or alternatively send a URL to the file(s). Notice that accounts in kit.net, or other servers that don’t upload to Finland, can’t be used.
If you don’t have an e-mail address, or if you want instant feedback to your report, contact Nix at ICQ (6160624) or, secondarily, Huntta (6220878).
If neither of the above work for you, but you can upload the files (if any are needed) to a FTP or HTTP server, you can leave a message with the URL on the English section of the Outgun Forum. In that case, make extra sure you don’t give any details you want to keep private (e.g. passwords in Outgun configuration files; the Dr. Watson logs may also include some information about your system which you can inspect by opening the log with Dr. Watson).