| How To Report A Bug |
| ------------------- |
| |
| There are two ways for you to make a bug report. One uses a simple perl |
| script, and is recommended if you don't want to spend a lot of time |
| producing the report. It is designed for use by just about anyone, from |
| the newest of newbies to advanced developers. You can also make a bug |
| report the hard way -- advanced developers will probably prefer this. |
| |
| A. 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 a message to the comp.emulators.ms-windows.wine newsgroup with the |
| "Nice Formatted Report" attatched. If possible, upload the full debug |
| output to a web/ftp server and provide the address in your message. |
| |
| |
| B. 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 installed |
| - 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 ! |
| |
| 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 msgs 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 your report to the newsgroup comp.emulators.ms-windows.wine |
| |
| In your post, include all of the information from part 1), and insert |
| the text from the output file in part 2). If you do this, your chances |
| of receiving some sort of helpful response should be very good. |
| |
| 4) 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 comp.emulators.ms-windows.wine to let us know |
| how this document can be improved. |
| |
| |
| |
| How to do regression testing using Cvs |
| ------------------------------------- |
| |
| A problem that can happen sometimes is 'it used to work before, |
| now it doesn't anymore...'. Here is a step by step procedure to |
| try to pinpoint when the problem occured. This is *NOT* for casual |
| users. |
| |
| 1) get the 'full cvs' archive from winehq. |
| This archive is the cvs tree but with the tags controling the versioning |
| system. It's a big file (> 15 meg) with a name like full-cvs-<last update date> |
| (it's more than 100mb when uncompressed, you can't very well do this |
| with small, old computers or slow Internet connections) |
| |
| 2) untar it into a repository directory : |
| |
| cd /home/gerard |
| tar -zxffull-cvs-2000-05-20.tar.gz |
| mv wine repository |
| |
| 3) extract a new destination directory |
| This directory must not be in a subdirectory of the repository else |
| cvs will think it's part of the repository and deny you an extraction |
| in the repository : |
| |
| cd /home/gerard |
| mv wine wine_current (-> this protects your current wine sandbox, if any) |
| export CVSROOT=/home/gerard/repository |
| cd /home/gerard |
| cvs -d $CVSROOT checkout wine |
| |
| Note that it's not possible to do a checkout at a given date; you |
| always do the checkout for the last date where the full-cvs-xxx snapshot |
| was generated. |
| |
| 4) you will have now in the ~/wine directory an image of the cvs tree, |
| on the client side. |
| Now update this image to the date you want : |
| |
| cd /home/gerard/wine |
| cvs -d $CVSROOT update -D "1999-06-01" |
| |
| The date format is YYYY-MM-DD. |
| |
| Many messages will inform you that more recent files have been |
| deleted to set back the client cvs tree to the date you asked, |
| for example : |
| |
| cvs update: tsx11/ts_xf86dga2.c is no longer in the repository |
| |
| Cvs update is not limited to upgrade to a *newer* version as |
| I have believed for far too long :-( |
| |
| 5) Now proceed as for a normal update : |
| |
| ./configure |
| make depend && make |
| |
| When you have found the exact date when a bug was |
| added to Cvs, use something like : |
| |
| cvs -d $CVSROOT diff -D "1999-07-10" -D "1999-07-12" |
| |
| to get all the differences between the last cvs version |
| known to work and code that first displayed the misbehavior. |
| |
| [ I did not include flags for diff since they are in my .cvsrc file : |
| cvs -z 3 |
| update -dPA |
| diff -u |
| ] |
| |
| From this diff file, particularly the file names, and the |
| ChangeLog, it's usually possible to find the different individual |
| patches that were done at this time. |
| |
| If any non-programmer reads this, the fasted method to get |
| at the point where the problem occured is to use a binary |
| search, that is, if the problem occured in 1999, start at mid-year, |
| then is the problem is already here, back to 1st avril, if not, |
| to 1st october, and so on. |
| |
| 6) The next step is to start from the last working version |
| and to dig the individual contributions from |
| http://www.integrita.com/cgi-local/lwgate.pl/WINE-PATCHES/ |
| (where the Wine patches mailing list is archived) |
| |
| If the patch was done by the Wine maintainer or if it was |
| sent directly to his mail address without going first through |
| wine-patches, you are out of luck as you will never find the |
| patch in the archive. |
| If it is, it's often possible to apply the patches one by |
| one to last working Cvs, compile and test. If you have saved |
| the next candidate as /home/gerard/buggedpatch1.txt : |
| |
| cd /home/gerard/wine |
| patch -p 0 </home/gerard/buggedpatch1.txt |
| |
| Beware that the committed patch is not always identical to |
| the patch that the author sent to wine-patches, as sometimes |
| the Wine maintainer changes things a bit. |
| |
| If you find one patch that is getting the Cvs to reproduce the problem, |
| you have almost won; post the problem on |
| comp.emulators.windows.wine |
| and there is a chance that the author will jump in to suggest a fix; |
| or there is always the possibility to look hard at the patch until it |
| is coerced to reveal where is the bug :-) |