documentation/bugs.sgml

  <chapter id="bugs">
    <title>Troubleshooting / Reporting bugs</title>

    <sect1 id="troubleshooting">
      <title>What to do if some program still doesn't work?</title>

      <para>
      There are times when you've been trying everything, you even killed a cat
      at full moon and ate it with rotten garlic and foul fish
      while doing the Devil's Dance, yet nothing helped to make some damn
      program work on some Wine version.
      Don't despair, we're here to help you...
      (in other words: how much do you want to pay ?)
      </para>
      
      <sect2>
        <title>Run "winecheck" to check your configuration</title>

	<para>
	  Run a Perl script called <command>winecheck</command>.
	  For details, please refer to the <link
	  linkend="config-verify">Configuration section</link>.
	</para>
      </sect2>

      <sect2>
        <title>Use different windows version settings</title>

	<para>
	In several cases using <link linkend="config-windows-versions">different windows version settings</link> can help.
        </para>
      </sect2>

      <sect2>
        <title>Use different startup paths</title>

	<para>
	  This sometimes helps, too:

	  Try to use both
	  <command>wine prg.exe</command>
	  and
	  <command>wine x:\\full\\path\\to\\prg.exe</command>
	</para>
      </sect2>

      <sect2>
        <title>Fiddle with DLL configuration</title>

	<para>
	  Run with --debugmsg +loaddll to figure out which DLLs are
	  being used, and whether they're being loaded as native or
	  built-in.
	  Then make sure you have proper native DLL files in your
	  configured C:\windows\system directory and fiddle with DLL
	  load order settings at command line or in config file.
	</para>
      </sect2>

      <sect2>
        <title>Check your system environment !</title>

	<para>
	  Just an idea: could it be that your Wine build/execution
	  environment is broken ?

	  Make sure that there are no problems whatsoever with the
	  packages
	  that Wine depends on (gcc, glibc, X libraries, OpenGL (!), ...)

	  E.g. some people have strange failures to find stuff when
	  using "wrong" header files for the "right" libraries !!!
	  (which results in days of debugging to desperately try to find
	  out why that lowlevel function fails in a way that is completely
	  beyond imagination... ARGH !)
	</para>
      </sect2>

      <sect2>
        <title>Use different GUI (Window Manager) modes</title>
	
	<para>
	  Instruct Wine via config file to use either desktop mode,
	  managed mode or plain ugly "normal" mode.
	  That can make one hell of a difference, too.
	</para>
      </sect2>

      <sect2>
        <title>Check your app !</title>
	
	<para>
	  Maybe your app is using some kind of copy protection ?

	  Many copy protections currently don't work on Wine.
	  Some might work in the future, though.
	  (the CD-ROM layer isn't really full-featured yet).
	</para>

	<para>
	  Go to <ulink
	  url="http://www.gamecopyworld.com">GameCopyWorld</ulink>
	  and try to find a decent crack for your game that gets rid of
	  that ugly copy protection.
	  I hope you do have a legal copy of the program, though... :-)
	</para>
      </sect2>

      <sect2>
        <title>Check your Wine environment !</title>
        
	<para>
	  Running with or without a Windows partition can have a
	  dramatic impact.

	  Configure Wine to do the opposite of what you used to have.

	  Also, install DCOM98 or DCOM95. This can be very beneficial.
	</para>
      </sect2>

      <sect2>
        <title>Reconfigure Wine</title>
	
	<para>
	  Sometimes wine installation process changes and new versions of
	  Wine account on these changes.
	  This is especially true if your setup was created long time ago.

	  Rename your existing <filename>~/.wine</filename> directory
	  for backup purposes.
	  Use the setup process that's recommended for your Wine distribution
	  to create new configuration.
	  Use information in old <filename>~/.wine</filename>
	  directory as a reference.
	  For source wine distribution to configure Wine run
	  tools/wineinstall script as a user you want to do the configuration
	  for.
	  This is a pretty safe operation. Later you can remove the new
	  <filename>~/.wine</filename> directory and rename your old one back.
	</para>
      </sect2>

      <sect2>
      <title>Check out further information</title>
      
      <para>
	There is a really good chance that someone has already tried
	to do the same thing as you.  You may find the 
	following resources helpful:
      </para>
      <para>
	<itemizedlist>
	  <listitem>
	    <para>
		Search <ulink url="http://appdb.winehq.org">WineHQ's
		Application Database</ulink> to check for any tips
		relating to the program.  If your specific version of
		the program isn't listed you may find a different one
		contains enough information to help you out.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		<ulink url="http://www.frankscorner.org">Frank's Corner</ulink>
		contains a list of applications and detailed instructions
		for setting them up.  Further help can be found in the user
		forums.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		<ulink url="http://www.google.com">Google</ulink> can be
		useful depending on how you use it.  You may
		find it helpful to search 
		<ulink url="http://groups.google.com">Google Groups</ulink>,
		in particular the 
		<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>
		group.  
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		<ulink url="http://www.freenode.net">Freenode.net</ulink>
		hosts an IRC channel for Wine.  You can access it by using
		any IRC client such as Xchat.  The settings you'll need are:
		server = irc.freenode.net, port = 6667, and channel = #winehq
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		If you have a program that needs the Visual Basic Runtime Enviroment,
		you can download it from
		<ulink url="http://www.microsoft.com/downloads/details.aspx?FamilyID=bf9a24f9-b5c5-48f4-8edd-cdf2d29a79d5&amp;DisplayLang=en/">this Microsoft site</ulink>
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		If you know you are missing a DLL, such as mfc42,
		you may be able to find it at
		<ulink url="http://www.dll-files.com/">www.dll-files.com</ulink>
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		Wine's <ulink url="http://www.winehq.org/site/forums#ml">mailing
		lists</ulink> may also help, especially wine-users.  The
		wine-devel list may be appropriate depending on the type of
		problem you are experiencing.  If you post to wine-devel you
		should be prepared to do a little work to help diagnose the
		problem.  Read the section below to find out how to debug
		the source of your problem.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
		If all else fails, you may wish to investigate commercial
		versions of Wine to see if your application is supported. 
	    </para>
	  </listitem>
	</itemizedlist>  
      </para>
      </sect2>

      <sect2>
        <title>Debug it!</title>

	<para>
	  Finding the source of your problem is the next step to take.
	  There is a wide spectrum of possible problems
	  ranging from simple configurations issues to completely unimplemented
	  functionality in Wine.  The next section will describe how to 
	  file a bug report and how to begin debugging a crash.  For more
	  information on using Wine's debugging facilities be sure to read
	  the Wine Developers Guide.
	</para>
      </sect2>
	
    </sect1>

    <sect1 id="bug-reporting">
      <title>How To Report A Bug</title>

      <para>
        Please report all bugs along any relevant information to
	<ulink url="http://bugs.winehq.org/">Wine Bugzilla</ulink>.
        Please, search the Bugzilla database to check whether your problem
        is already reported. If it is already reported please add
        any relevant information to the original bug report.
      </para>

      <sect2>
        <title>All Bug Reports</title>
        <para>
          Some simple advice on making your bug report more useful
          (and thus more likely to get answered and fixed):
        </para>
        <orderedlist>
          <listitem>
          <para>
            Post as much relevant information as possible.
          </para>
          <para>
            This means we need more information than a simple "MS
            Word crashes whenever I run it.  Do you know why?"
            Include at least the following information:
          </para>
          <itemizedlist spacing="compact">
            <listitem>
            <para>
              Which version of Wine you're using (run <command>wine -v</command>)
            </para>
            </listitem>
            <listitem>
            <para>
              The name of the Operating system you're using, what distribution (if
              any), and what version. (i.e., Linux Red Hat 7.2)
            </para>
            </listitem>
            <listitem>
            <para>
              Which compiler and version, (run <command>gcc -v</command>).
              If you didn't compile wine then the name of the package and
              where you got it from.
            </para>
            </listitem>
            <listitem>
            <para>
              Windows version, if used with Wine.
              Mention if you don't use Windows.
            </para>
            </listitem>
            <listitem>
            <para>
              The name of the program you're trying to run, its version number,
              and a URL for where the program can be obtained (if
              available).
            </para>
            </listitem>
            <listitem>
            <para>
              The exact command line you used to start wine. 
              (i.e., <command>wine "C:\Program Files\Test\program.exe"</command>).
             </para>
            </listitem>
            <listitem>
            <para>
              The exact steps required to reproduce the bug.
            </para>
            </listitem>
            <listitem>
            <para>
              Any other information you think may be relevant or
              helpful, such as X server version in case of X
              problems, libc version etc.
            </para>
            </listitem>
          </itemizedlist>
          </listitem>
          <listitem>
          <para>
            Re-run the program with the <parameter>--debugmsg
            +relay</parameter> option (i.e., <command>wine
            --debugmsg +relay sol.exe</command>).
          </para>
          <para>
            This will output additional information at the console 
            that may be helpful in debugging the program. It also
            slows the execution of program. There are some cases where 
            the bug seems to disappear when <parameter> +relay 
            </parameter> is used. Please mention that in the bug report.
          </para>
          </listitem>
        </orderedlist>
      </sect2>
      <sect2>
        <title>Crashes</title>
        <para>
           If Wine crashes while running your program, it is
           important that we have this information to have a chance
           at figuring out what is causing the crash.  This can put
           out quite a lot (several MB) of information, though, so
           it's best to output it to a file.  When the <prompt>Wine-dbg></prompt>
           prompt appears, type <userinput>quit</userinput>.
        </para>
        <para>
           You might want to try
           <parameter>+relay,+snoop</parameter> instead of
           <parameter>+relay</parameter>, but please note that
           <parameter>+snoop</parameter> is pretty unstable and
           often will crash earlier than a simple
           <parameter>+relay</parameter>! If this is the case, then
           please use <emphasis>only</emphasis> <parameter>+relay</parameter>!!
           A bug report with a crash in <parameter>+snoop</parameter>
           code is useless in most cases!
           You can also turn on other parameters, depending on the nature
           of the problem you are researching. See wine man page for full list
           of the parameters.
         </para>
         <para>
           To get the trace output, use one of the following methods:
         </para>
         <sect3>
           <title>The Easy Way</title>
           <orderedlist>
             <listitem>
             <para>
               This method is meant to allow even a total novice to
               submit a relevant trace log in the event of a crash.
             </para>
             <para>
               Your computer <emphasis>must</emphasis> have perl on it
               for this method to work. To find out if you have perl,
               run <command>which perl</command>. If it returns something like
               <filename>/usr/bin/perl</filename>, you're in business.
               Otherwise, skip on down to "The Hard Way". If you aren't
               sure, just keep on going. When you try to run the
               script, it will become <emphasis>very</emphasis> apparent
	       if you don't have perl.
             </para>
             </listitem>
             <listitem>
             <para>
               Change directory to <filename>&lt;dirs to wine>/tools</filename>
             </para>
             </listitem>
             <listitem>
             <para>
               Type in <command>./bug_report.pl</command> and follow
               the directions.
             </para>
             </listitem>
             <listitem>
             <para>
               Post the bug to
               <ulink url="http://bugs.winehq.org/">Wine Bugzilla</ulink>.
               Please, search Bugzilla database to check whether your problem is
               already found before posting a bug report.
               Include your own detailed description of the problem with
               relevant information. Attach the "Nice Formatted Report"
               to the submitted bug. Do not cut and paste the report
               in the bug description - it is pretty big.
               Keep the full debug output in case it will be needed by
               Wine developers.
             </para>
             </listitem>
           </orderedlist>
         </sect3>
         <sect3>
           <title>The Hard Way</title>
           <para>
             It is likely that only the last 100 or so lines of the
             trace are necessary to find out where the program crashes. 
             In order to get those last 100 lines we need to do the following
           </para>
           <orderedlist>
             <listitem>
             <para>
               Redirect all the output of <parameter> -debugmsg </parameter>
               to a file.
             </para>
             </listitem>
             <listitem>
             <para>
               Separate the last 100 lines to another file using
               <command>tail</command>.
             </para>
             </listitem>
           </orderedlist>
           <para>
             This can be done using one of the following methods.
           </para>
           <variablelist>
             <varlistentry>
             <term>all shells:</term>
             <listitem>
             <screen>
<prompt>$ </prompt>echo quit | wine -debugmsg +relay [other_options] program_name >& filename.out;
<prompt>$ </prompt>tail -n 100 filename.out > report_file
             </screen>
             <para>
               (This will print wine's debug messages only to the file 
               and then auto-quit. It's probably a good idea to use this 
               command, since wine prints out so many debug msgs that 
               they flood the terminal, eating CPU cycles.)
             </para>
             </listitem>
             </varlistentry>
             <varlistentry>
             <term>tcsh and other csh-like shells:</term>
             <listitem>
             <screen>
<prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name |& tee filename.out;
<prompt>$ </prompt>tail -n 100 filename.out > report_file
             </screen>
             </listitem>
             </varlistentry>
             <varlistentry>
             <term>bash and other sh-like shells:</term>
             <listitem>
             <screen>
<prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out;
<prompt>$ </prompt>tail -n 100 filename.out > report_file
             </screen>
             </listitem>
             </varlistentry>
          </variablelist>
          <para>
            <filename>report_file</filename> will now contain the
            last hundred lines of the debugging output, including
            the register dump and backtrace, which are the most
            important pieces of information.  Please do not delete
            this part, even if you don't understand what it means.
          </para>
          <para>
            Post the bug to 
            <ulink url="http://bugs.winehq.org/">Wine Bugzilla</ulink>.
            You need to attach the output file <filename>report_file</filename>
            from part 2). Along with the the relevant information 
            used to create it. Do not cut and paste the report
            in the bug description - it is pretty big and it will
            make a mess of the bug report.
            If you do this, your chances of receiving some sort of
            helpful response should be very good.
          </para>
          <para>
            Please, search the Bugzilla database to check whether your problem
            is already reported. If it is already reported attach the
            output file <filename>report_file</filename> to the original
            bug report and add any other relevant information.
          </para>
        </sect3>
      </sect2>
    </sect1>
 </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")
End:
-->