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