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