documentation/bugs.sgml

   1   <chapter id="bugs">
   2     <title>Troubleshooting / Reporting bugs</title>
   3
   4     <sect1 id="troubleshooting">
   5       <title>What to do if some program still doesn't work ?</title>
   6
   7       <para>
   8       There are times when you've been trying everything, you even killed a cat
   9       at full moon and ate it with rotten garlic and foul fish
  10       while doing the Devil's Dance, yet nothing helped to make some damn
  11       program work on some Wine version.
  12       Don't despair, we're here to help you...
  13       (in other words: how much do you want to pay ?)
  14       </para>
  15
  16       <sect2>
  17         <title>Run "winecheck" to check your configuration</title>
  18
  19         <para>
  20         Run a Perl script called <command>winecheck</command>, to be
  21         found in Wine's tools/ directory.
  22
  23         The latest version can always be found at
  24         <ulink
  25         url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.
  26
  27         Make sure to run <command>chmod +x winecheck</command> first before
  28         trying to execute it...
  29         (or alternatively run it via <command>perl ./winecheck</command>)
  30
  31         The winecheck output will be a percentage score indicating Wine
  32         configuration correctness.
  33         Note that winecheck is only alpha, so it's not very complete or
  34         100% accurate.
  35         </para>
  36       </sect2>
  37
  38       <sect2>
  39         <title>Use different windows version settings</title>
  40
  41         <para>
  42         In several cases using <link linkend="windows-versions">different windows version settings</link> can help.
  43         </para>
  44       </sect2>
  45
  46       <sect2>
  47         <title>Use different startup paths</title>
  48
  49         <para>
  50           This sometimes helps, too:
  51
  52           Try to use both
  53           <command>wine prg.exe</command>
  54           and
  55           <command>wine x:\\full\\path\\to\\prg.exe</command>
  56         </para>
  57       </sect2>
  58
  59       <sect2>
  60         <title>Fiddle with DLL configuration</title>
  61
  62         <para>
  63           Run with --debugmsg +loaddll to figure out which DLLs are
  64           being used, and whether they're being loaded as native or
  65           builtin.
  66           Then make sure you have proper native DLL files in your
  67           configured C:\windows\system directory and fiddle with DLL
  68           load order settings at command line or in config file.
  69         </para>
  70       </sect2>
  71
  72       <sect2>
  73         <title>Check your system environment !</title>
  74
  75         <para>
  76           Just an idea: could it be that your Wine build/execution
  77           environment is broken ?
  78
  79           Make sure that there are no problems whatsoever with the
  80           packages
  81           that Wine depends on (gcc, glibc, X libraries, OpenGL (!), ...)
  82
  83           E.g. some people have strange failures to find stuff when
  84           using "wrong" header files for the "right" libraries !!!
  85           (which results in days of debugging to desperately try to find
  86           out why that lowlevel function fails in a way that is completely
  87           beyond imagination... ARGH !)
  88         </para>
  89       </sect2>
  90
  91       <sect2>
  92         <title>Use different GUI (Window Manager) modes</title>
  93
  94         <para>
  95           Instruct Wine via config file to use either desktop mode,
  96           managed mode or plain ugly "normal" mode.
  97           That can make one hell of a difference, too.
  98         </para>
  99       </sect2>
 100
 101       <sect2>
 102         <title>Check your app !</title>
 103
 104         <para>
 105           Maybe your app is using some kind of copy protection ?
 106
 107           Many copy protections currently don't work on Wine.
 108           Some might work in the future, though.
 109           (the CD-ROM layer isn't really full-featured yet).
 110         </para>
 111
 112         <para>
 113           Go to <ulink
 114           url="http://www.gamecopyworld.com">GameCopyWorld</ulink>
 115           and try to find a decent crack for your game that gets rid of
 116           that ugly copy protection.
 117           I hope you do have a legal copy of the program, though... :-)
 118         </para>
 119       </sect2>
 120
 121       <sect2>
 122         <title>Check your Wine environment !</title>
 123
 124         <para>
 125           Running with or without a Windows partition can have a
 126           dramatic impact.
 127
 128           Configure Wine to do the opposite of what you used to have.
 129
 130           Also, install DCOM98 or DCOM95. This can be very beneficial.
 131         </para>
 132       </sect2>
 133
 134       <sect2>
 135         <title>Reconfigure Wine</title>
 136
 137         <para>
 138           Sometimes wine installation process changes and new versions of
 139           Wine acccount on these changes.
 140           This is especially true if your setup was created long time ago.
 141
 142           Rename your existing <filename>~/.wine</filename> directory
 143           for backup purposes.
 144           Use the setup process that's recommended for your Wine distribution
 145           to create new configuration.
 146           Use information in old <filename>~/.wine</filename>
 147           directory as a reference.
 148           For source wine distribution to configure Wine run
 149           tools/wineinstall script as a user you want to do the configuration
 150           for.
 151           This is a pretty safe operation. Later you can remove the new
 152           <filename>~/.wine</filename> directory and rename your old one back.
 153         </para>
 154       </sect2>
 155
 156       <sect2>
 157       <title>Check out further information</title>
 158
 159       <para>
 160         Check out the <ulink
 161         url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> on WineHQ.
 162
 163         Go to <ulink url="http://groups.google.com">Google Groups</ulink>
 164         and check whether some guys are smarter than you ;-)
 165         (well, whether they found a solution to the problem, that is)
 166
 167         Go to <ulink url="http://appdb.codeweavers.com">WineHQ's
 168         Application Database</ulink> and check whether
 169         someone posted the vital config hint for your app.
 170
 171         If that doesn't help, then consider going to
 172         irc.freenode.net channel #WineHQ, posting to
 173         news:comp.emulators.ms-windows.wine or mailing to the wine-users
 174         (or maybe sometimes even wine-devel) mailing lists.
 175       </para>
 176       </sect2>
 177
 178       <sect2>
 179         <title>Debug it!</title>
 180
 181         <para>
 182           Have you used the Search feature of the <ulink
 183           url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> ?? (i.e. are you sure there's no answer ?)
 184           If you have, then try
 185           <ulink url="http://www.winehq.org/fom-meta/cache/230.html">
 186           The Perfect Enduser Wine Debugging Guide</ulink>, and of
 187           course don't forget to read the Wine Developers Guide.
 188         </para>
 189       </sect2>
 190
 191     </sect1>
 192
 193     <sect1 id="bug-reporting">
 194       <title>How To Report A Bug</title>
 195
 196       <para>
 197         Please report all bugs along any relevant information to
 198         <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 199         Please, search the Bugzilla database to check whether your problem
 200         is already reported. If it is already reported please add
 201         any relevant information to the original bug report.
 202       </para>
 203
 204       <sect2>
 205         <title>All Bug Reports</title>
 206         <para>
 207           Some simple advice on making your bug report more useful
 208           (and thus more likely to get answered and fixed):
 209         </para>
 210         <orderedlist>
 211           <listitem>
 212           <para>Post as much relevant information as possible.</para>
 213           <para>
 214             This means we need more information than a simple "MS
 215             Word crashes whenever I run it.  Do you know why?"
 216             Include at least the following information:
 217           </para>
 218           <itemizedlist spacing="compact">
 219             <listitem>
 220             <para>
 221               Which version of Wine you're using (run <command>wine -v</command>)
 222             </para>
 223             </listitem>
 224             <listitem>
 225             <para>
 226               The name of the Operating system you're using, what distribution (if
 227               any), and what version. (i.e., Linux RedHat 7.2)
 228             </para>
 229             </listitem>
 230             <listitem>
 231             <para>
 232               Which compiler and version, (run <command>gcc -v</command>).
 233               If you didn't compile wine then the name of the package and
 234               where you got it from.
 235             </para>
 236             </listitem>
 237             <listitem>
 238             <para>
 239               Windows version, if used with Wine.
 240               Mention if you don't use Windows.
 241             </para>
 242             </listitem>
 243             <listitem>
 244             <para>
 245               The name of the program you're trying to run, its version number,
 246               and a URL for where the program can be obtained (if
 247               available).
 248             </para>
 249             </listitem>
 250             <listitem>
 251             <para>
 252               The exact command line you used to start wine.
 253               (i.e., <command>wine "C:\Program Files\Test\program.exe"</command>).
 254              </para>
 255             </listitem>
 256             <listitem>
 257             <para>
 258               The exact steps required to reproduce the bug.
 259             </para>
 260             </listitem>
 261             <listitem>
 262             <para>
 263               Any other information you think may be relevant or
 264               helpful, such as X server version in case of X
 265               problems, libc version etc.
 266             </para>
 267             </listitem>
 268           </itemizedlist>
 269           </listitem>
 270           <listitem>
 271           <para>
 272             Re-run the program with the <parameter>--debugmsg
 273             +relay</parameter> option (i.e., <command>wine
 274             --debugmsg +relay sol.exe</command>).
 275           </para>
 276           <para>
 277             This will output additional information at the console
 278             that may be helpfull in in debugging the program. It also
 279             slows the execution of program. There are some cases where
 280             the bug seems to dissappear when <parameter> +relay
 281             </parameter> is used. Please mention that in the bug report.
 282           </para>
 283           </listitem>
 284         </orderedlist>
 285       </sect2>
 286       <sect2>
 287         <title>Crashes</title>
 288         <para>
 289            If Wine crashes while running your program, it is
 290            important that we have this information to have a chance
 291            at figuring out what is causing the crash.  This can put
 292            out quite a lot (several MB) of information, though, so
 293            it's best to output it to a file.  When the <prompt>Wine-dbg></prompt>
 294            prompt appears, type <userinput>quit</userinput>.
 295         </para>
 296         <para>
 297            You might want to try
 298            <parameter>+relay,+snoop</parameter> instead of
 299            <parameter>+relay</parameter>, but please note that
 300            <parameter>+snoop</parameter> is pretty unstable and
 301            often will crash earlier than a simple
 302            <parameter>+relay</parameter>! If this is the case, then
 303            please use <emphasis>only</emphasis> <parameter>+relay</parameter>!!
 304            A bug report with a crash in <parameter>+snoop</parameter>
 305            code is useless in most cases!
 306            You can also turn on other parameters, depending on the nature
 307            of the problem you are researching. See wine man page for full list
 308            of the parameters.
 309          </para>
 310          <para>
 311            To get the trace output, use one of the following methods:
 312          </para>
 313          <sect3>
 314            <title>The Easy Way</title>
 315            <orderedlist>
 316              <listitem>
 317              <para>
 318                This method is meant to allow even a total novice to
 319                submit a relevent trace log in the event of a crash.
 320              </para>
 321              <para>
 322                Your computer <emphasis>must</emphasis> have perl on it
 323                for this method to work. To find out if you have perl,
 324                run <command>which perl</command>. If it returns something like
 325                <filename>/usr/bin/perl</filename>, you're in business.
 326                Otherwise, skip on down to "The Hard Way". If you aren't
 327                sure, just keep on going. When you try to run the
 328                script, it will become <emphasis>very</emphasis> apparent
 329                if you don't have perl.
 330              </para>
 331              </listitem>
 332              <listitem>
 333              <para>
 334                Change directory to <filename>&lt;dirs to wine>/tools</filename>
 335              </para>
 336              </listitem>
 337              <listitem>
 338              <para>
 339                Type in <command>./bug_report.pl</command> and follow
 340                the directions.
 341              </para>
 342              </listitem>
 343              <listitem>
 344              <para>
 345                Post the bug to
 346                <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 347                Please, search Bugzilla database to check whether your problem is
 348                already found before posting a bug report.
 349                Include your own detailed description of the problem with
 350                relevant information. Attach the "Nice Formatted Report"
 351                to the submitted bug. Do not cut and paste the report
 352                in the bug description - it is pretty big.
 353                Keep the full debug output in case it will be needed by
 354                Wine developers.
 355              </para>
 356              </listitem>
 357            </orderedlist>
 358          </sect3>
 359          <sect3>
 360            <title>The Hard Way</title>
 361            <para>
 362              It is likely that only the last 100 or so lines of the
 363              trace are nessesary to find out where the program crashes.
 364              In order to get those last 100 lines we need to do the following
 365            </para>
 366            <orderedlist>
 367              <listitem>
 368              <para>
 369                Redirect all the output of <parameter> -debugmsg </parameter>
 370                to a file.
 371              </para>
 372              </listitem>
 373              <listitem>
 374              <para>
 375                Separate the last 100 lines to another file using
 376                <command> tail </command>.
 377              </para>
 378              </listitem>
 379            </orderedlist>
 380            <para>
 381              This can be done using one of the following methods.
 382            </para>
 383            <variablelist>
 384              <varlistentry>
 385              <term>all shells:</term>
 386              <listitem>
 387              <screen>
 388 <prompt>$ </prompt>echo quit | wine -debugmsg +relay [other_options] program_name >& filename.out;
 389 <prompt>$ </prompt>tail -n 100 filename.out > report_file
 390              </screen>
 391              <para>
 392                (This will print wine's debug messages only to the file
 393                and then auto-quit. It's probably a good idea to use this
 394                command, since wine prints out so many debug msgs that
 395                they flood the terminal, eating CPU cycles.)
 396              </para>
 397              </listitem>
 398              </varlistentry>
 399              <varlistentry>
 400              <term>tcsh and other csh-like shells:</term>
 401              <listitem>
 402              <screen>
 403 <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name |& tee filename.out;
 404 <prompt>$ </prompt>tail -100 filename.out > report_file
 405              </screen>
 406              </listitem>
 407              </varlistentry>
 408              <varlistentry>
 409              <term>bash and other sh-like shells:</term>
 410              <listitem>
 411              <screen>
 412 <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out;
 413 <prompt>$ </prompt>tail -100 filename.out > report_file
 414              </screen>
 415              </listitem>
 416              </varlistentry>
 417           </variablelist>
 418           <para>
 419             <filename>report_file</filename> will now contain the
 420             last hundred lines of the debugging output, including
 421             the register dump and backtrace, which are the most
 422             important pieces of information.  Please do not delete
 423             this part, even if you don't understand what it means.
 424           </para>
 425           <para>
 426             Post the bug to
 427             <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 428             You need to attach the output file <filename>report_file</filename>
 429             from part 2). Along with the the relevant information
 430             used to create it. Do not cut and paste the report
 431             in the bug description - it is pretty big and it will
 432             make a mess of the bug report.
 433             If you do this, your chances of receiving some sort of
 434             helpful response should be very good.
 435           </para>
 436           <para>
 437             Please, search the Bugzilla database to check whether your problem
 438             is already reported. If it is already reported attach the
 439             output file <filename>report_file</filename> to the original
 440             bug report and add any other relevant information.
 441           </para>
 442         </sect3>
 443       </sect2>
 444     </sect1>
 445  </chapter>
 446
 447 <!-- Keep this comment at the end of the file
 448 Local variables:
 449 mode: sgml
 450 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 451 End:
 452 -->