211 lines
7.7 KiB
Plaintext
211 lines
7.7 KiB
Plaintext
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 :-)
|