documentation/bugs.sgml

   1   <chapter id="bugs">
   2     <title>Finding and Reporting Bugs</title>
   3
   4     <sect1 id="bug-reporting">
   5       <title>How To Report A Bug</title>
   6
   7       <para>
   8         Written by &name-gerard-patel; <email>&email-gerard-patel;</email>
   9       </para>
  10       <para>
  11         (Extracted from <filename>wine/documentation/bugreports</filename>)
  12       </para>
  13
  14       <para>
  15         There are two ways for you to make a bug report. One uses a
  16         simple perl script, and is recommended if you don't want to
  17         spend a lot of time producing the report. It is designed for
  18         use by just about anyone, from the newest of newbies to
  19         advanced developers. You can also make a bug report the hard
  20         way -- advanced developers will probably prefer this.
  21       </para>
  22
  23       <sect2>
  24         <title>The Easy Way</title>
  25         <orderedlist>
  26           <listitem>
  27             <para>
  28               Your computer <emphasis>must</emphasis> have perl on it
  29               for this method to work. To find out if you have perl,
  30               run <command>which perl</command>. If it returns something like
  31               <filename>/usr/bin/perl</filename>, you're in business.
  32               Otherwise, skip on down to "The Hard Way". If you aren't
  33               sure, just keep on going. When you try to run the
  34               script, it will become <emphasis>very</emphasis> apparent
  35               if you don't have perl.
  36             </para>
  37           </listitem>
  38           <listitem>
  39             <para>
  40               Change directory to <filename>&lt;dirs to
  41                 wine>/tools</filename>
  42             </para>
  43           </listitem>
  44           <listitem>
  45               <para>
  46                 Type in <command>./bug_report.pl</command> and follow
  47                 the directions.
  48             </para>
  49           </listitem>
  50           <listitem>
  51             <para>
  52               Post a message to the
  53               <systemitem>comp.emulators.ms-windows.wine</systemitem>
  54               newsgroup with the "Nice Formatted Report" attatched. If
  55               possible, upload the full debug output to a web/ftp
  56               server and provide the address in your message.
  57             </para>
  58           </listitem>
  59         </orderedlist>
  60       </sect2>
  61
  62       <sect2>
  63         <title>The Hard Way</title>
  64         <para>
  65           Some simple advice on making your bug report more useful
  66           (and thus more likely to get answered and fixed):
  67         </para>
  68         <orderedlist>
  69           <listitem>
  70             <para>Post as much information as possible.</para>
  71             <para>
  72               This means we need more information than a simple "MS
  73               Word crashes whenever I run it.  Do you know why?"
  74               Include at least the following information:
  75             </para>
  76             <itemizedlist spacing="compact">
  77               <listitem>
  78                 <para>Version of Wine you're using (run <command>wine
  79                     -v</command>)</para>
  80               </listitem>
  81               <listitem>
  82                 <para>
  83                   Operating system you're using, what distribution (if
  84                   any), and what version
  85                 </para>
  86               </listitem>
  87               <listitem>
  88                 <para>Compiler and version (run <command>gcc -v</command>)</para>
  89               </listitem>
  90               <listitem>
  91                 <para>Windows version, if installed</para>
  92               </listitem>
  93               <listitem>
  94                 <para>
  95                   Program you're trying to run, its version number,
  96                   and a URL for  where the program can be obtained (if
  97                   available)
  98                 </para>
  99               </listitem>
 100               <listitem>
 101                 <para>Command line you used to start wine</para>
 102               </listitem>
 103               <listitem>
 104                 <para>
 105                   Any other information you think may be relevant or
 106                   helpful, such as X server version in case of X
 107                   problems, libc version etc.
 108                 </para>
 109               </listitem>
 110             </itemizedlist>
 111           </listitem>
 112           <listitem>
 113             <para>
 114               Re-run the program with the <parameter>--debugmsg
 115                 +relay</parameter> option (i.e., <command>wine
 116                 --debugmsg +relay sol.exe</command>).
 117             </para>
 118             <para>
 119               If Wine crashes while running your program, it is
 120               important that we have this information to have a chance
 121               at figuring out what is causing the crash.  This can put
 122               out quite a lot (several MB) of information, though, so
 123               it's best to output it to a file.  When the <prompt>Wine-dbg></prompt>
 124               prompt appears, type <userinput>quit</userinput>.
 125             </para>
 126             <para>
 127               You might want to try
 128               <parameter>+relay,+snoop</parameter> instead of
 129               <parameter>+relay</parameter>, but please note that
 130               <parameter>+snoop</parameter> is pretty unstable and
 131               often will crash earlier than a simple
 132               <parameter>+relay</parameter>! If this is the case, then
 133               please use <emphasis>only</emphasis> <parameter>+relay</parameter>!! A bug
 134               report with a crash in <parameter>+snoop</parameter>
 135               code is useless in most cases!
 136             </para>
 137             <para>
 138               To get the trace output, use the following commands:
 139             </para>
 140
 141             <variablelist>
 142               <varlistentry>
 143                 <term>all shells:</term>
 144                 <listitem>
 145                   <screen>
 146 <prompt>$ </prompt>echo quit | wine -debugmsg +relay [other_options] program_name >& filename.out;
 147 <prompt>$ </prompt>tail -n 100 filename.out > report_file
 148                   </screen>
 149                   <para>
 150                     (This will print wine's debug messages only to the file and then
 151                     auto-quit. It's probably a good idea to use this command, since wine
 152                     prints out so many debug msgs that they flood the terminal, eating CPU.)
 153                   </para>
 154                 </listitem>
 155               </varlistentry>
 156               <varlistentry>
 157                 <term>tcsh and other csh-like shells:</term>
 158                 <listitem>
 159                   <screen>
 160 <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name |& tee filename.out;
 161 <prompt>$ </prompt>tail -100 filename.out > report_file
 162                   </screen>
 163                 </listitem>
 164               </varlistentry>
 165               <varlistentry>
 166                 <term>bash and other sh-like shells:</term>
 167                 <listitem>
 168                   <screen>
 169 <prompt>$ </prompt>wine -debugmsg +relay [other_options] program_name 2>&1 | tee filename.out;
 170 <prompt>$ </prompt>tail -100 filename.out > report_file
 171                   </screen>
 172                 </listitem>
 173               </varlistentry>
 174             </variablelist>
 175             <para>
 176               <filename>report_file</filename> will now contain the
 177               last hundred lines of the debugging output, including
 178               the register dump and backtrace, which are the most
 179               important pieces of information.  Please do not delete
 180               this part, even if you don't understand what it means.
 181             </para>
 182           </listitem>
 183           <listitem>
 184             <para>
 185               Post your report to the newsgroup
 186               <systemitem>comp.emulators.ms-windows.wine</systemitem>
 187             </para>
 188             <para>
 189               In your post, include all of the information from part
 190               1), and insert the text from the output file in part 2).
 191               If you do this, your chances of receiving some sort of
 192               helpful response should be very good.
 193             </para>
 194           </listitem>
 195         </orderedlist>
 196       </sect2>
 197
 198       <sect2>
 199         <title>Questions and comments</title>
 200         <para>
 201           If after reading this document there is something you
 202           couldn't figure out, or think could be explained better, or
 203           that should have been included, please post to
 204           <systemitem>comp.emulators.ms-windows.wine</systemitem> to
 205           let us know how this document can be improved.
 206         </para>
 207       </sect2>
 208     </sect1>
 209  </chapter>
 210
 211 <!-- Keep this comment at the end of the file
 212 Local variables:
 213 mode: sgml
 214 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 215 End:
 216 -->