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