| <chapter id="bugs"> |
| <title>Troubleshooting / Reporting bugs</title> |
| |
| <sect1 id="troubleshooting"> |
| <title>What to do if some program still doesn't work ?</title> |
| |
| <para> |
| There are times when you've been trying everything, you even killed a cat |
| at full moon and ate it with rotten garlic and foul fish |
| while doing the Devil's Dance, yet nothing helped to make some damn |
| program work on some Wine version. |
| Don't despair, we're here to help you... |
| (in other words: how much do you want to pay ?) |
| </para> |
| |
| <sect2> |
| <title>Run "winecheck" to check your configuration</title> |
| |
| <para> |
| Run a Perl script called <command>winecheck</command>, to be |
| found in Wine's tools/ directory. |
| |
| The latest version can always be found at |
| <ulink |
| url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>. |
| |
| Make sure to run <command>chmod +x winecheck</command> first before |
| trying to execute it... |
| (or alternatively run it via <command>perl ./winecheck</command>) |
| |
| The winecheck output will be a percentage score indicating Wine |
| configuration correctness. |
| Note that winecheck is only alpha, so it's not very complete or |
| 100% accurate. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Use different windows version settings</title> |
| |
| <para> |
| In several cases using <link linkend="windows-versions">different windows version settings</link> can help. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Use different startup paths</title> |
| |
| <para> |
| This sometimes helps, too: |
| |
| Try to use both |
| <command>wine prg.exe</command> |
| and |
| <command>wine x:\\full\\path\\to\\prg.exe</command> |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Fiddle with DLL configuration</title> |
| |
| <para> |
| Run with --debugmsg +loaddll to figure out which DLLs are |
| being used, and whether they're being loaded as native or |
| builtin. |
| Then make sure you have proper native DLL files in your |
| configured C:\windows\system directory and fiddle with DLL |
| load order settings at command line or in config file. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Check your system environment !</title> |
| |
| <para> |
| Just an idea: could it be that your Wine build/execution |
| environment is broken ? |
| |
| Make sure that there are no problems whatsoever with the |
| packages |
| that Wine depends on (gcc, glibc, X libraries, OpenGL (!), ...) |
| |
| E.g. some people have strange failures to find stuff when |
| using "wrong" header files for the "right" libraries !!! |
| (which results in days of debugging to desperately try to find |
| out why that lowlevel function fails in a way that is completely |
| beyond imagination... ARGH !) |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Use different GUI (Window Manager) modes</title> |
| |
| <para> |
| Instruct Wine via config file to use either desktop mode, |
| managed mode or plain ugly "normal" mode. |
| That can make one hell of a difference, too. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Check your app !</title> |
| |
| <para> |
| Maybe your app is using some kind of copy protection ? |
| |
| Many copy protections currently don't work on Wine. |
| Some might work in the future, though. |
| (the CD-ROM layer isn't really full-featured yet). |
| </para> |
| |
| <para> |
| Go to <ulink |
| url="http://www.gamecopyworld.com">GameCopyWorld</ulink> |
| and try to find a decent crack for your game that gets rid of |
| that ugly copy protection. |
| I hope you do have a legal copy of the program, though... :-) |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Check your Wine environment !</title> |
| |
| <para> |
| Running with or without a Windows partition can have a |
| dramatic impact. |
| |
| Configure Wine to do the opposite of what you used to have. |
| |
| Also, install DCOM98 or DCOM95. This can be very beneficial. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Reconfigure Wine</title> |
| |
| <para> |
| Sometimes wine installation process changes and new versions of |
| Wine acccount on these changes. |
| This is especially true if your setup was created long time ago. |
| |
| Rename your existing <filename>~/.wine</filename> directory |
| for backup purposes. |
| Use the setup process that's recommended for your Wine distribution |
| to create new configuration. |
| Use information in old <filename>~/.wine</filename> |
| directory as a reference. |
| For source wine distribution to configure Wine run |
| tools/wineinstall script as a user you want to do the configuration |
| for. |
| This is a pretty safe operation. Later you can remove the new |
| <filename>~/.wine</filename> directory and rename your old one back. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Check out further information</title> |
| |
| <para> |
| Check out the <ulink |
| url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> on WineHQ. |
| |
| Go to <ulink url="http://groups.google.com">Google Groups</ulink> |
| and check whether some guys are smarter than you ;-) |
| (well, whether they found a solution to the problem, that is) |
| |
| Go to <ulink url="http://appdb.codeweavers.com">WineHQ's |
| Application Database</ulink> and check whether |
| someone posted the vital config hint for your app. |
| |
| If that doesn't help, then consider going to |
| irc.openprojects.net channel #WineHQ, posting to |
| news:comp.emulators.ms-windows.wine or mailing to the wine-users |
| (or maybe sometimes even wine-devel) mailing lists. |
| </para> |
| </sect2> |
| |
| <sect2> |
| <title>Debug it!</title> |
| |
| <para> |
| Have you used the Search feature of the <ulink |
| url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> ?? (i.e. are you sure there's no answer ?) |
| If you have, then try |
| <ulink url="http://www.winehq.org/fom-meta/cache/230.html"> |
| The Perfect Enduser Wine Debugging Guide</ulink>, and of |
| course don't forget to read the Wine Developers Guide. |
| </para> |
| </sect2> |
| |
| </sect1> |
| |
| <sect1 id="bug-reporting"> |
| <title>How To Report A Bug</title> |
| |
| <para> |
| Please report all bugs along any relevant information to |
| <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>. |
| Please, search the Bugzilla database to check whether your problem |
| is already reported. If it is already reported please add |
| any relevant information to the original bug report. |
| </para> |
| |
| <sect2> |
| <title>All Bug Reports</title> |
| <para> |
| Some simple advice on making your bug report more useful |
| (and thus more likely to get answered and fixed): |
| </para> |
| <orderedlist> |
| <listitem> |
| <para>Post as much relevant information as possible.</para> |
| <para> |
| 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: |
| </para> |
| <itemizedlist spacing="compact"> |
| <listitem> |
| <para> |
| Which version of Wine you're using (run <command>wine -v</command>) |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The name of the Operating system you're using, what distribution (if |
| any), and what version. (i.e., Linux RedHat 7.2) |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Which compiler and version, (run <command>gcc -v</command>). |
| If you didn't compile wine then the name of the package and |
| where you got it from. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Windows version, if used with Wine. |
| Mention if you don't use Windows. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The name of the program you're trying to run, its version number, |
| and a URL for where the program can be obtained (if |
| available). |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The exact command line you used to start wine. |
| (i.e., <command>wine "C:\Program Files\Test\program.exe"</command>). |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| The exact steps required to reproduce the bug. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Any other information you think may be relevant or |
| helpful, such as X server version in case of X |
| problems, libc version etc. |
| </para> |
| </listitem> |
| </itemizedlist> |
| </listitem> |
| <listitem> |
| <para> |
| Re-run the program with the <parameter>--debugmsg |
| +relay</parameter> option (i.e., <command>wine |
| --debugmsg +relay sol.exe</command>). |
| </para> |
| <para> |
| This will output additional information at the console |
| that may be helpfull in in debugging the program. It also |
| slows the execution of program. There are some cases where |
| the bug seems to dissappear when <parameter> +relay |
| </parameter> is used. Please mention that in the bug report. |
| </para> |
| </listitem> |
| </orderedlist> |
| </sect2> |
| <sect2> |
| <title>Crashes</title> |
| <para> |
| 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 <prompt>Wine-dbg></prompt> |
| prompt appears, type <userinput>quit</userinput>. |
| </para> |
| <para> |
| You might want to try |
| <parameter>+relay,+snoop</parameter> instead of |
| <parameter>+relay</parameter>, but please note that |
| <parameter>+snoop</parameter> is pretty unstable and |
| often will crash earlier than a simple |
| <parameter>+relay</parameter>! If this is the case, then |
| please use <emphasis>only</emphasis> <parameter>+relay</parameter>!! |
| A bug report with a crash in <parameter>+snoop</parameter> |
| code is useless in most cases! |
| You can also turn on other parameters, depending on the nature |
| of the problem you are researching. See wine man page for full list |
| of the parameters. |
| </para> |
| <para> |
| To get the trace output, use one of the following methods: |
| </para> |
| <sect3> |
| <title>The Easy Way</title> |
| <orderedlist> |
| <listitem> |
| <para> |
| This method is meant to allow even a total novice to |
| submit a relevent trace log in the event of a crash. |
| </para> |
| <para> |
| Your computer <emphasis>must</emphasis> have perl on it |
| for this method to work. To find out if you have perl, |
| run <command>which perl</command>. If it returns something like |
| <filename>/usr/bin/perl</filename>, 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 <emphasis>very</emphasis> apparent |
| if you don't have perl. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Change directory to <filename><dirs to wine>/tools</filename> |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Type in <command>./bug_report.pl</command> and follow |
| the directions. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Post the bug to |
| <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>. |
| Please, search Bugzilla database to check whether your problem is |
| already found before posting a bug report. |
| Include your own detailed description of the problem with |
| relevant information. Attach the "Nice Formatted Report" |
| to the submitted bug. Do not cut and paste the report |
| in the bug description - it is pretty big. |
| Keep the full debug output in case it will be needed by |
| Wine developers. |
| </para> |
| </listitem> |
| </orderedlist> |
| </sect3> |
| <sect3> |
| <title>The Hard Way</title> |
| <para> |
| It is likely that only the last 100 or so lines of the |
| trace are nessesary to find out where the program crashes. |
| In order to get those last 100 lines we need to do the following |
| </para> |
| <orderedlist> |
| <listitem> |
| <para> |
| Redirect all the output of <parameter> -debugmsg </parameter> |
| to a file. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Separate the last 100 lines to another file using |
| <command> tail </command>. |
| </para> |
| </listitem> |
| </orderedlist> |
| <para> |
| This can be done using one of the following methods. |
| </para> |
| <variablelist> |
| <varlistentry> |
| <term>all shells:</term> |
| <listitem> |
| <screen> |
| <prompt>$ </prompt>echo quit | wine -debugmsg +relay [other_options] program_name >& filename.out; |
| <prompt>$ </prompt>tail -n 100 filename.out > report_file |
| </screen> |
| <para> |
| (This will print wine's debug messages 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 cycles.) |
| </para> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>tcsh and other csh-like shells:</term> |
| <listitem> |
| <screen> |
| <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name |& tee filename.out; |
| <prompt>$ </prompt>tail -100 filename.out > report_file |
| </screen> |
| </listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>bash and other sh-like shells:</term> |
| <listitem> |
| <screen> |
| <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out; |
| <prompt>$ </prompt>tail -100 filename.out > report_file |
| </screen> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| <para> |
| <filename>report_file</filename> 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. |
| </para> |
| <para> |
| Post the bug to |
| <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>. |
| You need to attach the output file <filename>report_file</filename> |
| from part 2). Along with the the relevant information |
| used to create it. Do not cut and paste the report |
| in the bug description - it is pretty big and it will |
| make a mess of the bug report. |
| If you do this, your chances of receiving some sort of |
| helpful response should be very good. |
| </para> |
| <para> |
| Please, search the Bugzilla database to check whether your problem |
| is already reported. If it is already reported attach the |
| output file <filename>report_file</filename> to the original |
| bug report and add any other relevant information. |
| </para> |
| </sect3> |
| </sect2> |
| </sect1> |
| </chapter> |
| |
| <!-- Keep this comment at the end of the file |
| Local variables: |
| mode: sgml |
| sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "") |
| End: |
| --> |