  <chapter id="bugs">
    <title>Finding and Reporting Bugs</title>

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

      <para>
        Written by (???)
      </para>
      <para>
        (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:
-->