documentation/bugreports - wine - Git at Google

 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 :-)
	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 :-)