documentation/bugs.sgml - wine - Git at Google

   <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>, to be
 	found in Wine's tools/ directory.

 	The latest version can always be found at
 	<ulink
 	url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.

 	Make sure to run <command>chmod +x winecheck</command> first before
 	trying to execute it...
 	(or alternatively run it via <command>perl ./winecheck</command>)

 	The winecheck output will be a percentage score indicating Wine
 	configuration correctness.
 	Note that winecheck is only alpha, so it's not very complete or
 	100% accurate.
 	</para>
       </sect2>

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

 	<para>
 	In several cases using <link linkend="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
 	  builtin.
 	  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 acccount 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>
         Check out the <ulink
 	url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> on WineHQ.

 	Go to <ulink url="http://groups.google.com">Google Groups</ulink>
 	and check whether some guys are smarter than you ;-)
 	(well, whether they found a solution to the problem, that is)

 	Go to <ulink url="http://appdb.codeweavers.com">WineHQ's
 	Application Database</ulink> and check whether
 	someone posted the vital config hint for your app.

 	If that doesn't help, then consider going to
 	irc.openprojects.net channel #WineHQ, posting to
 	news:comp.emulators.ms-windows.wine or mailing to the wine-users
 	(or maybe sometimes even wine-devel) mailing lists.
       </para>
       </sect2>

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

 	<para>
 	  Have you used the Search feature of the <ulink
 	  url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> ?? (i.e. are you sure there's no answer ?)
 	  If you have, then try
 	  <ulink url="http://www.winehq.org/fom-meta/cache/230.html">
 	  The Perfect Enduser Wine Debugging Guide</ulink>, and of
 	  course don't forget to read the Wine Developers Guide.
 	</para>
       </sect2>

     </sect1>

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

       <para>
         Written by (???)
       </para>
       <para>
         (Originally extracted from <filename>wine/documentation/bugreports</filename>)
       </para>

       <para>
         There are two ways for you to make a bug report. One uses a
         simple perl script, and is recommended if you don't want to
         spend a lot of time producing the report. It is designed for
         use by just about anyone, from the newest of newbies to
         advanced developers. You can also make a bug report the hard
         way -- advanced developers will probably prefer this.
       </para>
       <para>
         When using either approach please report the problem you found
         along with any relevant information to
 	<ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
       </para>

       <sect2>
         <title>The Easy Way</title>
         <orderedlist>
           <listitem>
             <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.com/">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>
       </sect2>

       <sect2>
         <title>The Hard Way</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 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>Version of Wine you're using (run <command>wine
                     -v</command>)</para>
               </listitem>
               <listitem>
                 <para>
                   Operating system you're using, what distribution (if
                   any), and what version
                 </para>
               </listitem>
               <listitem>
                 <para>Compiler and version (run <command>gcc -v</command>)</para>
               </listitem>
               <listitem>
                 <para>Windows version, if used with Wine.
 		Mention if you don't use Windows</para>
               </listitem>
               <listitem>
                 <para>
                   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>Command line you used to start wine</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>
               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 the following commands:
             </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.)
                   </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 -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 -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>
           </listitem>
           <listitem>
             <para>
               Post the bug to <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
               Please, search the Bugzilla database to check whether your problem
               is already reported. If it is already reported attach the bug report
               and add any other relevant information to the original bug report.
             </para>
             <para>
               In your post, include all of the information from part
               1), and attach to the bug the output file in part 2).
               If you do this, your chances of receiving some sort of
               helpful response should be very good.
             </para>
           </listitem>
         </orderedlist>
       </sect2>
     </sect1>
  </chapter>

 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 End:
 -->
	<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>, to be
	found in Wine's tools/ directory.

	The latest version can always be found at
	<ulink
	url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.

	Make sure to run <command>chmod +x winecheck</command> first before
	trying to execute it...
	(or alternatively run it via <command>perl ./winecheck</command>)

	The winecheck output will be a percentage score indicating Wine
	configuration correctness.
	Note that winecheck is only alpha, so it's not very complete or
	100% accurate.
	</para>
	</sect2>

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

	<para>
	In several cases using <link linkend="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
	builtin.
	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 acccount 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>
	Check out the <ulink
	url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> on WineHQ.

	Go to <ulink url="http://groups.google.com">Google Groups</ulink>
	and check whether some guys are smarter than you ;-)
	(well, whether they found a solution to the problem, that is)

	Go to <ulink url="http://appdb.codeweavers.com">WineHQ's
	Application Database</ulink> and check whether
	someone posted the vital config hint for your app.

	If that doesn't help, then consider going to
	irc.openprojects.net channel #WineHQ, posting to
	news:comp.emulators.ms-windows.wine or mailing to the wine-users
	(or maybe sometimes even wine-devel) mailing lists.
	</para>
	</sect2>

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

	<para>
	Have you used the Search feature of the <ulink
	url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> ?? (i.e. are you sure there's no answer ?)
	If you have, then try
	<ulink url="http://www.winehq.org/fom-meta/cache/230.html">
	The Perfect Enduser Wine Debugging Guide</ulink>, and of
	course don't forget to read the Wine Developers Guide.
	</para>
	</sect2>

	</sect1>

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

	<para>
	Written by (???)
	</para>
	<para>
	(Originally extracted from <filename>wine/documentation/bugreports</filename>)
	</para>

	<para>
	There are two ways for you to make a bug report. One uses a
	simple perl script, and is recommended if you don't want to
	spend a lot of time producing the report. It is designed for
	use by just about anyone, from the newest of newbies to
	advanced developers. You can also make a bug report the hard
	way -- advanced developers will probably prefer this.
	</para>
	<para>
	When using either approach please report the problem you found
	along with any relevant information to
	<ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
	</para>

	<sect2>
	<title>The Easy Way</title>
	<orderedlist>
	<listitem>
	<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><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.com/">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>
	</sect2>

	<sect2>
	<title>The Hard Way</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 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>Version of Wine you're using (run <command>wine
	-v</command>)</para>
	</listitem>
	<listitem>
	<para>
	Operating system you're using, what distribution (if
	any), and what version
	</para>
	</listitem>
	<listitem>
	<para>Compiler and version (run <command>gcc -v</command>)</para>
	</listitem>
	<listitem>
	<para>Windows version, if used with Wine.
	Mention if you don't use Windows</para>
	</listitem>
	<listitem>
	<para>
	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>Command line you used to start wine</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>
	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 the following commands:
	</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.)
	</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 -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 -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>
	</listitem>
	<listitem>
	<para>
	Post the bug to <ulink url="http://bugs.winehq.com/">Wine Bugzilla</ulink>.
	Please, search the Bugzilla database to check whether your problem
	is already reported. If it is already reported attach the bug report
	and add any other relevant information to the original bug report.
	</para>
	<para>
	In your post, include all of the information from part
	1), and attach to the bug the output file in part 2).
	If you do this, your chances of receiving some sort of
	helpful response should be very good.
	</para>
	</listitem>
	</orderedlist>
	</sect2>
	</sect1>
	</chapter>

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