6.1.1. The Easy Way

1. Your computer must have perl on it for this method to work. To find out if you have perl, run which perl. If it returns something like /usr/bin/perl, you're in business. Otherwise, skip on down to "The Hard Way". If you aren't sure, just keep on going. When you try to run the script, it will become very apparent if you don't have perl.

2. Change directory to <dirs to wine>/tools

3. Type in ./bug_report.pl and follow the directions.

4. Post the bug to Wine Bugzilla. Please, search Bugzilla database to check whether your problem is already found before posting a bug report. Include your own detailed description of the problem with relevant information. Attach the "Nice Formatted Report" to the submitted bug. Do not cut and paste the report in the bug description - it is pretty big. Keep the full debug output in case it will be needed by Wine developers.

6.1.2. The Hard Way

Some simple advice on making your bug report more useful (and thus more likely to get answered and fixed):

1. Post as much information as possible.

   This means we need more information than a simple "MS Word crashes whenever I run it. Do you know why?" Include at least the following information:

   • Version of Wine you're using (run wine -v)

   • Operating system you're using, what distribution (if any), and what version

   • Compiler and version (run gcc -v)

   • Windows version, if used with Wine. Mention if you don't use Windows

   • Program you're trying to run, its version number, and a URL for where the program can be obtained (if available)

   • Command line you used to start wine

   • Any other information you think may be relevant or helpful, such as X server version in case of X problems, libc version etc.

2. Re-run the program with the --debugmsg +relay option (i.e., wine --debugmsg +relay sol.exe).

   If Wine crashes while running your program, it is important that we have this information to have a chance at figuring out what is causing the crash. This can put out quite a lot (several MB) of information, though, so it's best to output it to a file. When the Wine-dbg> prompt appears, type quit.

   You might want to try +relay,+snoop instead of +relay, but please note that +snoop is pretty unstable and often will crash earlier than a simple +relay! If this is the case, then please use only +relay!! A bug report with a crash in +snoop code is useless in most cases! You can also turn on other parameters, depending on the nature of the problem you are researching. See wine man page for full list of the parameters.

   To get the trace output, use the following commands:

   all shells:

   $ echo quit | wine -debugmsg +relay [other_options] program_name >& filename.out; $ tail -n 100 filename.out > report_file

   (This will print wine's debug messages only to the file and then auto-quit. It's probably a good idea to use this command, since wine prints out so many debug msgs that they flood the terminal, eating CPU.)

   tcsh and other csh-like shells:

   $ wine -debugmsg +relay [other_options] program_name |& tee filename.out; $ tail -100 filename.out > report_file

   bash and other sh-like shells:

   $ wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out; $ tail -100 filename.out > report_file

   report_file will now contain the last hundred lines of the debugging output, including the register dump and backtrace, which are the most important pieces of information. Please do not delete this part, even if you don't understand what it means.

3. Post the bug to Wine Bugzilla. Please, search the Bugzilla database to check whether your problem is already reported. If it is already reported attach the bug report and add any other relevant information to the original bug report.

   In your post, include all of the information from part 1), and attach to the bug the output file in part 2). If you do this, your chances of receiving some sort of helpful response should be very good.

6.1.3. Questions and comments

If after reading this document there is something you couldn't figure out, or think could be explained better, or that should have been included, please post to Wine Bugzilla to let us know how this document can be improved.