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.
 100
 101
 102
 103 How to do regression testing using Cvs
 104 -------------------------------------
 105
 106 A problem that can happen sometimes is 'it used to work before,
 107 now it doesn't anymore...'. Here is a step by step procedure to
 108 try to pinpoint when the problem occured. This is *NOT* for casual
 109 users.
 110
 111 1) get the 'full cvs' archive from winehq.
 112 This archive is the cvs tree but with the tags controling the versioning
 113 system. It's a big file (> 15 meg) with a name like full-cvs-<last update date>
 114 (it's more than 100mb when uncompressed, you can't very well do this
 115 with small, old computers or slow Internet connections)
 116
 117 2) untar it into a repository directory :
 118
 119 cd /home/gerard
 120 tar -zxffull-cvs-2000-05-20.tar.gz
 121 mv wine repository
 122
 123 3) extract a new destination directory
 124 This directory must not be in a subdirectory of the repository else
 125 cvs will think it's part of the repository and deny you an extraction
 126 in the repository :
 127
 128 cd /home/gerard
 129 mv wine wine_current (-> this protects your current wine sandbox, if any)
 130 export CVSROOT=/home/gerard/repository
 131 cd /home/gerard
 132 cvs -d $CVSROOT checkout wine
 133
 134 Note that it's not possible to do a checkout at a given date; you
 135 always do the checkout for the last date where the full-cvs-xxx snapshot
 136 was generated.
 137
 138 4) you will have now in the ~/wine directory an image of the cvs tree,
 139 on the client side.
 140 Now update this image to the date you want :
 141
 142 cd /home/gerard/wine
 143 cvs -d $CVSROOT update -D "1999-06-01"
 144
 145 The date format is YYYY-MM-DD.
 146
 147 Many messages will inform you that more recent files have been
 148 deleted to set back the client cvs tree to the date you asked,
 149 for example :
 150
 151 cvs update: tsx11/ts_xf86dga2.c is no longer in the repository
 152
 153 Cvs update is not limited to upgrade to a *newer* version as
 154 I have believed for far too long :-(
 155
 156 5) Now proceed as for a normal update :
 157
 158 ./configure
 159 make depend && make
 160
 161 When you have found the exact date when a bug was
 162 added to Cvs, use something like :
 163
 164 cvs -d $CVSROOT diff -D "1999-07-10" -D "1999-07-12"
 165
 166 to get all the differences between the last cvs version
 167 known to work and code that first displayed the misbehavior.
 168
 169  [ I did not include flags for diff since they are in my .cvsrc file :
 170    cvs -z 3
 171    update -dPA
 172    diff -u
 173  ]
 174
 175 From this diff file, particularly  the file names, and the
 176 ChangeLog, it's usually possible to find the different individual
 177 patches that were done at this time.
 178
 179 If any non-programmer reads this, the fasted method to get
 180 at the point where the problem occured is to use a binary
 181 search, that is, if the problem occured in 1999, start at mid-year,
 182 then is the problem is already here, back to 1st avril, if not,
 183 to 1st october, and so on.
 184
 185 6) The next step is to start from the last working version
 186 and to dig the individual contributions from
 187 http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/
 188 (where the Wine patches mailing list is archived)
 189
 190 If the patch was done by the Wine maintainer or if it was
 191 sent directly to his mail address without going first through
 192 wine-patches, you are out of luck as you will never find the
 193 patch in the archive.
 194 If it is, it's often possible to apply the patches one by
 195 one to last working Cvs, compile and test. If you have saved
 196 the next candidate as /home/gerard/buggedpatch1.txt :
 197
 198 cd /home/gerard/wine
 199 patch -p 0 </home/gerard/buggedpatch1.txt
 200
 201 Beware that the committed patch is not always identical to
 202 the patch that the author sent to wine-patches, as sometimes
 203 the Wine maintainer changes things a bit.
 204
 205 If you find one patch that is getting the Cvs to reproduce the problem,
 206 you have almost won; post the problem on
 207 comp.emulators.windows.wine
 208 and there is a chance that the author will jump in to suggest a fix;
 209 or there is always the possibility to look hard at the patch until it
 210 is coerced to reveal where is the bug :-)