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 acccount 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         Check out the <ulink
 149         url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> on WineHQ.
 150
 151         Go to <ulink url="http://groups.google.com">Google Groups</ulink>
 152         and check whether some guys are smarter than you ;-)
 153         (well, whether they found a solution to the problem, that is)
 154
 155         Go to <ulink url="http://appdb.codeweavers.com">WineHQ's
 156         Application Database</ulink> and check whether
 157         someone posted the vital config hint for your app.
 158
 159         If that doesn't help, then consider going to
 160         irc.freenode.net channel #WineHQ, posting to
 161         news:comp.emulators.ms-windows.wine or mailing to the wine-users
 162         (or maybe sometimes even wine-devel) mailing lists.
 163       </para>
 164       </sect2>
 165
 166       <sect2>
 167         <title>Debug it!</title>
 168
 169         <para>
 170           Have you used the Search feature of the <ulink
 171           url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> ?? (i.e. are you sure there's no answer ?)
 172           If you have, then try
 173           <ulink url="http://www.winehq.org/fom-meta/cache/230.html">
 174           The Perfect Enduser Wine Debugging Guide</ulink>, and of
 175           course don't forget to read the Wine Developers Guide.
 176         </para>
 177       </sect2>
 178
 179     </sect1>
 180
 181     <sect1 id="bug-reporting">
 182       <title>How To Report A Bug</title>
 183
 184       <para>
 185         Please report all bugs along any relevant information to
 186         <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 187         Please, search the Bugzilla database to check whether your problem
 188         is already reported. If it is already reported please add
 189         any relevant information to the original bug report.
 190       </para>
 191
 192       <sect2>
 193         <title>All Bug Reports</title>
 194         <para>
 195           Some simple advice on making your bug report more useful
 196           (and thus more likely to get answered and fixed):
 197         </para>
 198         <orderedlist>
 199           <listitem>
 200           <para>Post as much relevant information as possible.</para>
 201           <para>
 202             This means we need more information than a simple "MS
 203             Word crashes whenever I run it.  Do you know why?"
 204             Include at least the following information:
 205           </para>
 206           <itemizedlist spacing="compact">
 207             <listitem>
 208             <para>
 209               Which version of Wine you're using (run <command>wine -v</command>)
 210             </para>
 211             </listitem>
 212             <listitem>
 213             <para>
 214               The name of the Operating system you're using, what distribution (if
 215               any), and what version. (i.e., Linux Red Hat 7.2)
 216             </para>
 217             </listitem>
 218             <listitem>
 219             <para>
 220               Which compiler and version, (run <command>gcc -v</command>).
 221               If you didn't compile wine then the name of the package and
 222               where you got it from.
 223             </para>
 224             </listitem>
 225             <listitem>
 226             <para>
 227               Windows version, if used with Wine.
 228               Mention if you don't use Windows.
 229             </para>
 230             </listitem>
 231             <listitem>
 232             <para>
 233               The name of the program you're trying to run, its version number,
 234               and a URL for where the program can be obtained (if
 235               available).
 236             </para>
 237             </listitem>
 238             <listitem>
 239             <para>
 240               The exact command line you used to start wine.
 241               (i.e., <command>wine "C:\Program Files\Test\program.exe"</command>).
 242              </para>
 243             </listitem>
 244             <listitem>
 245             <para>
 246               The exact steps required to reproduce the bug.
 247             </para>
 248             </listitem>
 249             <listitem>
 250             <para>
 251               Any other information you think may be relevant or
 252               helpful, such as X server version in case of X
 253               problems, libc version etc.
 254             </para>
 255             </listitem>
 256           </itemizedlist>
 257           </listitem>
 258           <listitem>
 259           <para>
 260             Re-run the program with the <parameter>--debugmsg
 261             +relay</parameter> option (i.e., <command>wine
 262             --debugmsg +relay sol.exe</command>).
 263           </para>
 264           <para>
 265             This will output additional information at the console
 266             that may be helpfull in in debugging the program. It also
 267             slows the execution of program. There are some cases where
 268             the bug seems to dissappear when <parameter> +relay
 269             </parameter> is used. Please mention that in the bug report.
 270           </para>
 271           </listitem>
 272         </orderedlist>
 273       </sect2>
 274       <sect2>
 275         <title>Crashes</title>
 276         <para>
 277            If Wine crashes while running your program, it is
 278            important that we have this information to have a chance
 279            at figuring out what is causing the crash.  This can put
 280            out quite a lot (several MB) of information, though, so
 281            it's best to output it to a file.  When the <prompt>Wine-dbg></prompt>
 282            prompt appears, type <userinput>quit</userinput>.
 283         </para>
 284         <para>
 285            You might want to try
 286            <parameter>+relay,+snoop</parameter> instead of
 287            <parameter>+relay</parameter>, but please note that
 288            <parameter>+snoop</parameter> is pretty unstable and
 289            often will crash earlier than a simple
 290            <parameter>+relay</parameter>! If this is the case, then
 291            please use <emphasis>only</emphasis> <parameter>+relay</parameter>!!
 292            A bug report with a crash in <parameter>+snoop</parameter>
 293            code is useless in most cases!
 294            You can also turn on other parameters, depending on the nature
 295            of the problem you are researching. See wine man page for full list
 296            of the parameters.
 297          </para>
 298          <para>
 299            To get the trace output, use one of the following methods:
 300          </para>
 301          <sect3>
 302            <title>The Easy Way</title>
 303            <orderedlist>
 304              <listitem>
 305              <para>
 306                This method is meant to allow even a total novice to
 307                submit a relevent trace log in the event of a crash.
 308              </para>
 309              <para>
 310                Your computer <emphasis>must</emphasis> have perl on it
 311                for this method to work. To find out if you have perl,
 312                run <command>which perl</command>. If it returns something like
 313                <filename>/usr/bin/perl</filename>, you're in business.
 314                Otherwise, skip on down to "The Hard Way". If you aren't
 315                sure, just keep on going. When you try to run the
 316                script, it will become <emphasis>very</emphasis> apparent
 317                if you don't have perl.
 318              </para>
 319              </listitem>
 320              <listitem>
 321              <para>
 322                Change directory to <filename>&lt;dirs to wine>/tools</filename>
 323              </para>
 324              </listitem>
 325              <listitem>
 326              <para>
 327                Type in <command>./bug_report.pl</command> and follow
 328                the directions.
 329              </para>
 330              </listitem>
 331              <listitem>
 332              <para>
 333                Post the bug to
 334                <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 335                Please, search Bugzilla database to check whether your problem is
 336                already found before posting a bug report.
 337                Include your own detailed description of the problem with
 338                relevant information. Attach the "Nice Formatted Report"
 339                to the submitted bug. Do not cut and paste the report
 340                in the bug description - it is pretty big.
 341                Keep the full debug output in case it will be needed by
 342                Wine developers.
 343              </para>
 344              </listitem>
 345            </orderedlist>
 346          </sect3>
 347          <sect3>
 348            <title>The Hard Way</title>
 349            <para>
 350              It is likely that only the last 100 or so lines of the
 351              trace are nessesary to find out where the program crashes.
 352              In order to get those last 100 lines we need to do the following
 353            </para>
 354            <orderedlist>
 355              <listitem>
 356              <para>
 357                Redirect all the output of <parameter> -debugmsg </parameter>
 358                to a file.
 359              </para>
 360              </listitem>
 361              <listitem>
 362              <para>
 363                Separate the last 100 lines to another file using
 364                <command> tail </command>.
 365              </para>
 366              </listitem>
 367            </orderedlist>
 368            <para>
 369              This can be done using one of the following methods.
 370            </para>
 371            <variablelist>
 372              <varlistentry>
 373              <term>all shells:</term>
 374              <listitem>
 375              <screen>
 376 <prompt>$ </prompt>echo quit | wine -debugmsg +relay [other_options] program_name >& filename.out;
 377 <prompt>$ </prompt>tail -n 100 filename.out > report_file
 378              </screen>
 379              <para>
 380                (This will print wine's debug messages only to the file
 381                and then auto-quit. It's probably a good idea to use this
 382                command, since wine prints out so many debug msgs that
 383                they flood the terminal, eating CPU cycles.)
 384              </para>
 385              </listitem>
 386              </varlistentry>
 387              <varlistentry>
 388              <term>tcsh and other csh-like shells:</term>
 389              <listitem>
 390              <screen>
 391 <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name |& tee filename.out;
 392 <prompt>$ </prompt>tail -100 filename.out > report_file
 393              </screen>
 394              </listitem>
 395              </varlistentry>
 396              <varlistentry>
 397              <term>bash and other sh-like shells:</term>
 398              <listitem>
 399              <screen>
 400 <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out;
 401 <prompt>$ </prompt>tail -100 filename.out > report_file
 402              </screen>
 403              </listitem>
 404              </varlistentry>
 405           </variablelist>
 406           <para>
 407             <filename>report_file</filename> will now contain the
 408             last hundred lines of the debugging output, including
 409             the register dump and backtrace, which are the most
 410             important pieces of information.  Please do not delete
 411             this part, even if you don't understand what it means.
 412           </para>
 413           <para>
 414             Post the bug to
 415             <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 416             You need to attach the output file <filename>report_file</filename>
 417             from part 2). Along with the the relevant information
 418             used to create it. Do not cut and paste the report
 419             in the bug description - it is pretty big and it will
 420             make a mess of the bug report.
 421             If you do this, your chances of receiving some sort of
 422             helpful response should be very good.
 423           </para>
 424           <para>
 425             Please, search the Bugzilla database to check whether your problem
 426             is already reported. If it is already reported attach the
 427             output file <filename>report_file</filename> to the original
 428             bug report and add any other relevant information.
 429           </para>
 430         </sect3>
 431       </sect2>
 432     </sect1>
 433  </chapter>
 434
 435 <!-- Keep this comment at the end of the file
 436 Local variables:
 437 mode: sgml
 438 sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")
 439 End:
 440 -->