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.openprojects.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         Written by (???)
 198       </para>
 199       <para>
 200         (Originally extracted from <filename>wine/documentation/bugreports</filename>)
 201       </para>
 202
 203       <para>
 204         There are two ways for you to make a bug report. One uses a
 205         simple perl script, and is recommended if you don't want to
 206         spend a lot of time producing the report. It is designed for
 207         use by just about anyone, from the newest of newbies to
 208         advanced developers. You can also make a bug report the hard
 209         way -- advanced developers will probably prefer this.
 210       </para>
 211       <para>
 212         When using either approach please report the problem you found
 213         along with any relevant information to
 214         <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 215       </para>
 216
 217       <sect2>
 218         <title>The Easy Way</title>
 219         <orderedlist>
 220           <listitem>
 221             <para>
 222               Your computer <emphasis>must</emphasis> have perl on it
 223               for this method to work. To find out if you have perl,
 224               run <command>which perl</command>. If it returns something like
 225               <filename>/usr/bin/perl</filename>, you're in business.
 226               Otherwise, skip on down to "The Hard Way". If you aren't
 227               sure, just keep on going. When you try to run the
 228               script, it will become <emphasis>very</emphasis> apparent
 229               if you don't have perl.
 230             </para>
 231           </listitem>
 232           <listitem>
 233             <para>
 234               Change directory to <filename>&lt;dirs to
 235                 wine>/tools</filename>
 236             </para>
 237           </listitem>
 238           <listitem>
 239               <para>
 240                 Type in <command>./bug_report.pl</command> and follow
 241                 the directions.
 242             </para>
 243           </listitem>
 244           <listitem>
 245             <para>
 246               Post the bug to
 247               <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 248               Please, search Bugzilla database to check whether your problem is
 249               already found before posting a bug report.
 250               Include your own detailed description of the problem with
 251               relevant information. Attach the "Nice Formatted Report"
 252               to the submitted bug. Do not cut and paste the report
 253               in the bug description - it is pretty big.
 254               Keep the full debug output in case it will be needed by
 255               Wine developers.
 256             </para>
 257           </listitem>
 258         </orderedlist>
 259       </sect2>
 260
 261       <sect2>
 262         <title>The Hard Way</title>
 263         <para>
 264           Some simple advice on making your bug report more useful
 265           (and thus more likely to get answered and fixed):
 266         </para>
 267         <orderedlist>
 268           <listitem>
 269             <para>Post as much information as possible.</para>
 270             <para>
 271               This means we need more information than a simple "MS
 272               Word crashes whenever I run it.  Do you know why?"
 273               Include at least the following information:
 274             </para>
 275             <itemizedlist spacing="compact">
 276               <listitem>
 277                 <para>Version of Wine you're using (run <command>wine
 278                     -v</command>)</para>
 279               </listitem>
 280               <listitem>
 281                 <para>
 282                   Operating system you're using, what distribution (if
 283                   any), and what version
 284                 </para>
 285               </listitem>
 286               <listitem>
 287                 <para>Compiler and version (run <command>gcc -v</command>)</para>
 288               </listitem>
 289               <listitem>
 290                 <para>Windows version, if used with Wine.
 291                 Mention if you don't use Windows</para>
 292               </listitem>
 293               <listitem>
 294                 <para>
 295                   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>Command line you used to start wine</para>
 302               </listitem>
 303               <listitem>
 304                 <para>
 305                   Any other information you think may be relevant or
 306                   helpful, such as X server version in case of X
 307                   problems, libc version etc.
 308                 </para>
 309               </listitem>
 310             </itemizedlist>
 311           </listitem>
 312           <listitem>
 313             <para>
 314               Re-run the program with the <parameter>--debugmsg
 315                 +relay</parameter> option (i.e., <command>wine
 316                 --debugmsg +relay sol.exe</command>).
 317             </para>
 318             <para>
 319               If Wine crashes while running your program, it is
 320               important that we have this information to have a chance
 321               at figuring out what is causing the crash.  This can put
 322               out quite a lot (several MB) of information, though, so
 323               it's best to output it to a file.  When the <prompt>Wine-dbg></prompt>
 324               prompt appears, type <userinput>quit</userinput>.
 325             </para>
 326             <para>
 327               You might want to try
 328               <parameter>+relay,+snoop</parameter> instead of
 329               <parameter>+relay</parameter>, but please note that
 330               <parameter>+snoop</parameter> is pretty unstable and
 331               often will crash earlier than a simple
 332               <parameter>+relay</parameter>! If this is the case, then
 333               please use <emphasis>only</emphasis> <parameter>+relay</parameter>!! A bug
 334               report with a crash in <parameter>+snoop</parameter>
 335               code is useless in most cases!
 336               You can also turn on other parameters, depending on the nature
 337               of the problem you are researching. See wine man page for full list
 338               of the parameters.
 339             </para>
 340             <para>
 341               To get the trace output, use the following commands:
 342             </para>
 343
 344             <variablelist>
 345               <varlistentry>
 346                 <term>all shells:</term>
 347                 <listitem>
 348                   <screen>
 349 <prompt>$ </prompt>echo quit | wine -debugmsg +relay [other_options] program_name >& filename.out;
 350 <prompt>$ </prompt>tail -n 100 filename.out > report_file
 351                   </screen>
 352                   <para>
 353                     (This will print wine's debug messages only to the file and then
 354                     auto-quit. It's probably a good idea to use this command, since wine
 355                     prints out so many debug msgs that they flood the terminal, eating CPU.)
 356                   </para>
 357                 </listitem>
 358               </varlistentry>
 359               <varlistentry>
 360                 <term>tcsh and other csh-like shells:</term>
 361                 <listitem>
 362                   <screen>
 363 <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name |& tee filename.out;
 364 <prompt>$ </prompt>tail -100 filename.out > report_file
 365                   </screen>
 366                 </listitem>
 367               </varlistentry>
 368               <varlistentry>
 369                 <term>bash and other sh-like shells:</term>
 370                 <listitem>
 371                   <screen>
 372 <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out;
 373 <prompt>$ </prompt>tail -100 filename.out > report_file
 374                   </screen>
 375                 </listitem>
 376               </varlistentry>
 377             </variablelist>
 378             <para>
 379               <filename>report_file</filename> will now contain the
 380               last hundred lines of the debugging output, including
 381               the register dump and backtrace, which are the most
 382               important pieces of information.  Please do not delete
 383               this part, even if you don't understand what it means.
 384             </para>
 385           </listitem>
 386           <listitem>
 387             <para>
 388               Post the bug to <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
 389               Please, search the Bugzilla database to check whether your problem
 390               is already reported. If it is already reported attach the bug report
 391               and add any other relevant information to the original bug report.
 392             </para>
 393             <para>
 394               In your post, include all of the information from part
 395               1), and attach to the bug the output file in part 2).
 396               If you do this, your chances of receiving some sort of
 397               helpful response should be very good.
 398             </para>
 399           </listitem>
 400         </orderedlist>
 401       </sect2>
 402     </sect1>
 403  </chapter>
 404
 405 <!-- Keep this comment at the end of the file
 406 Local variables:
 407 mode: sgml
 408 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 409 End:
 410 -->