documentation/bugreports

   1 How To Report A Bug
   2 -------------------
   3
   4 There are two ways for you to make a bug report. One uses a simple perl
   5 script, and is recommended if you don't want to spend a lot of time
   6 producing the report. It is designed for use by just about anyone, from
   7 the newest of newbies to advanced developers. You can also make a bug
   8 report the hard way -- advanced developers will probably prefer this.
   9
  10 A. The Easy Way
  11 1) Your computer *must* have perl on it for this method to work. To
  12 find out if you have perl, run:
  13 which perl
  14 If it returns something like "/usr/bin/perl", you're in business.
  15 Otherwise, skip on down to "The Hard Way".
  16 If you aren't sure, just keep on going. When you try to run the script, it
  17 will become *very* apparent if you don't have perl.
  18
  19 2) Change directory to <dirs to wine>/tools
  20
  21 3) Type in "./bug_report.pl" and follow the directions.
  22
  23 4) Post a message to the comp.emulators.ms-windows.wine newsgroup with the
  24 "Nice Formatted Report" attatched. If possible, upload the full debug
  25 output to a web/ftp server and provide the address in your message.
  26
  27
  28 B. The Hard Way:
  29
  30 Some simple advice on making your bug report more useful (and thus more
  31 likely to get answered and fixed):
  32
  33 1) Post as much information as possible.
  34
  35         This means we need more information than a simple
  36         "MS Word crashes whenever I run it.  Do you know why?"
  37         Include at least the following information:
  38
  39         - Version of Wine you're using (run 'wine -v')
  40         - Operating system you're using, what distribution (if any), and what
  41                 version
  42         - Compiler and version (run 'gcc -v')
  43         - Windows version, if installed
  44         - Program you're trying to run, its version number, and a URL for
  45                 where the program can be obtained (if available)
  46         - Command line you used to start wine
  47         - Any other information you think may be relevant or helpful, such as
  48                 X server version in case of X problems, libc version etc.
  49
  50 2) Re-run the program with the -debugmsg +relay option
  51    (i.e., 'wine -debugmsg +relay sol.exe').
  52
  53         If Wine crashes while running your program, it is important that we
  54         have this information to have a chance at figuring out what is causing
  55         the crash.  This can put out quite a lot (several MB) of information,
  56         though, so it's best to output it to a file.  When the Wine-dbg> prompt
  57         appears, type 'quit'.
  58
  59         You might want to try +relay,+snoop instead of +relay, but please note
  60     that +snoop is pretty unstable and often will crash earlier than a
  61     simple +relay !
  62         If this is the case, then please use *only* +relay !!
  63         A bug report with a crash in +snoop code is useless in most cases !
  64
  65         To get the trace output, use the following commands:
  66
  67         all shells:
  68             echo quit|wine -debugmsg +relay [other_options] program_name >& filename.out; tail -n 100 filename.out > report_file
  69         (This will print wine's debug msgs only to the file and then
  70         auto-quit. It's probably a good idea to use this command, since wine
  71         prints out so many debug msgs that they flood the terminal, eating CPU.)
  72
  73         tcsh and other csh-like shells:
  74
  75             wine -debugmsg +relay [other_options] program_name |& tee filename.out
  76             tail -100 filename.out > report_file
  77
  78         bash and other sh-like shells:
  79
  80             wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out
  81             tail -100 filename.out > report_file
  82
  83         'report_file' will now contain the last hundred lines of the debugging
  84         output, including the register dump and backtrace, which are the most
  85         important pieces of information.  Please do not delete this part, even
  86         if you don't understand what it means.
  87
  88 3) Post your report to the newsgroup comp.emulators.ms-windows.wine
  89
  90         In your post, include all of the information from part 1), and insert
  91         the text from the output file in part 2).  If you do this, your chances
  92         of receiving some sort of helpful response should be very good.
  93
  94 4) Questions and comments
  95
  96         If after reading this document there is something you couldn't figure
  97         out, or think could be explained better, or that should have been
  98         included, please post to comp.emulators.ms-windows.wine to let us know
  99         how this document can be improved.