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 /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- (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