Merged display.dll into USER.

[wine.git] / documentation / bugreports

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