path: root/DOCS/xml/en/bugreports.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<appendix id="bugreports">
<title>How to report bugs</title>

<para>
Good bug reports are a very valuable contribution to the development of any
software project. But just like writing good software, good problem reports
involve some work. Please realize that most developers are extremely busy and
receive obscene amounts of email. So while your feedback is crucial in improving
<application>MPlayer</application> and very much appreciated, please understand
that you have to provide <emphasis role="bold">all</emphasis> of the information
we request and follow the instructions in this document closely.
</para>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_security">
<title>Report security related bugs</title>

<para>
In case you have found an exploitable bug and you would like to do the
right thing and let us fix it before you disclose it, we would be happy
to get your security advisory at
<ulink url="mailto:&#115;&#101;&#99;&#117;&#114;&#105;&#116;&#121;&#64;&#109;&#112;&#108;&#97;&#121;&#101;&#114;&#104;&#113;&#46;&#104;&#117;">&#115;&#101;&#99;&#117;&#114;&#105;&#116;&#121;&#64;&#109;&#112;&#108;&#97;&#121;&#101;&#114;&#104;&#113;&#46;&#104;&#117;</ulink>.
Please add [SECURITY] or [ADVISORY] in the subject.
Be sure that your report contains complete and detailed analysis of the bug.
Sending a fix is highly appreciated.
Please don't delay your report to write proof-of-concept exploit, you can
send that one with another mail.
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_fix">
<title>How to fix bugs</title>

<para>
OUTDATED CONTENT REMOVED
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_regression_test">
<title>How to do regression testing using Subversion</title>

<para>
OUTDATED CONTENT REMOVED
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_report">
<title>How to report bugs</title>

<para>
OUTDATED CONTENT REMOVED
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_where">
<title>Where to report bugs</title>

<para>
OUTDATED CONTENT REMOVED
</para>

<para>
The language of this list is <emphasis role="bold">English</emphasis>.
Please follow the standard
<ulink url="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</ulink>
and <emphasis role="bold">do not send HTML mail</emphasis> to any of our
mailing lists. You will only get ignored or
banned. If you do not know what HTML mail is or why it is evil, read this
<ulink url="http://efn.no/html-bad.html">fine document</ulink>.
It explains all the details and has instructions for turning HTML off. Also
note that we will not individually CC (carbon-copy) people so it is a good idea
to subscribe to actually receive your answer.
</para>
</sect1>


<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->


<sect1 id="bugreports_what">
<title>What to report</title>

<para>
OUTDATED CONTENT REMOVED
</para>

<!-- ********** -->

<sect2 id="bugreports_system">
<title>System Information</title>

<para>
OUTDATED CONTENT REMOVED
</para>
</sect2>

<!-- ********** -->

<sect2 id="bugreports_hardware">
<title>Hardware and drivers</title>

<para>
OUTDATED CONTENT REMOVED
</para>
</sect2>

<!-- ********** -->

<sect2 id="bugreports_configure">
<title>Configure problems</title>

<para>
If you get errors while running <command>./configure</command>, or autodetection
of something fails, read <filename>config.log</filename>. You may find the
answer there, for example multiple versions of the same library mixed on your
system, or you forgot to install the development package (those with the -dev
suffix). If you think there is a bug, include <filename>config.log</filename>
in your bug report.
</para>
</sect2>

<sect2 id="bugreports_compilation">
<title>Compilation problems</title>

<para>
Please include these files:
<itemizedlist>
  <listitem><para>config.h</para></listitem>
  <listitem><para>config.mak</para></listitem>
</itemizedlist>
</para>
</sect2>

<!-- ********** -->

<sect2 id="bugreports_playback">
<title>Playback problems</title>

<para>
Please include the output of <application>MPlayer</application> at verbosity
level 1, but remember to
<emphasis role="bold">not truncate the output</emphasis> when
you paste it into your mail. The developers need all of the messages to properly
diagnose a problem. You can direct the output into a file like this:
<screen>
mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> &gt; mplayer.log 2&gt;&amp;1
</screen>
</para>

<para>
If your problem is specific to one or more files,
then please upload the offender(s) to:
<ulink url="ftp://upload.mplayerhq.hu/MPlayer/incoming/"/>
</para>

<para>
Also upload a small text file having the same base name as your file with a .txt
extension. Describe the problem you are having with the particular file there
and include your email address as well as the output of
<application>MPlayer</application> at verbosity level 1.
Usually the first 1-5 MB of a file are enough to reproduce
the problem, but to be sure we ask you to:
<screen>
dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5
</screen>
It will take the first five megabytes of
'<emphasis role="bold">your-file</emphasis>' and write it to
'<emphasis role="bold">small-file</emphasis>'. Then try again on
this small file and if the bug still shows up your sample is sufficient for us.
Please <emphasis role="bold">do not ever</emphasis> send such files via mail!
Upload it, and send only the path/filename of the file on the FTP-server. If the
file is accessible on the net, then sending the
<emphasis role="bold">exact</emphasis> URL is sufficient.
</para>
</sect2>

<!-- ********** -->

<sect2 id="bugreports_crash">
<title>Crashes</title>

<para>
You have to run <application>MPlayer</application> inside <command>gdb</command>
and send us the complete output or if you have a <filename>core</filename> dump
of the crash you can extract useful information from the Core file. Here's how:
</para>


<sect3 id="bugreports_debug">
<title>How to conserve information about a reproducible crash</title>

<para>
Recompile <application>MPlayer</application> with debugging code enabled:
<screen>
./configure --enable-debug=3
make
</screen>
and then run <application>MPlayer</application> within gdb using:
<screen>gdb ./mplayer</screen>
You are now within gdb. Type:
<screen>
run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable>
</screen>
and reproduce your crash. As soon as you did it, gdb will return you to the
command line prompt where you have to enter
<screen>
bt
disass $pc-32 $pc+32
info all-registers
</screen>
</para>
</sect3>


<sect3 id="bugreports_core">
<title>How to extract meaningful information from a core dump</title>

<para>
Create the following command file:
<screen>
bt
disass $pc-32 $pc+32
info all-registers
</screen>
Then simply execute this command:
<screen>
gdb mplayer --core=core -batch --command=command_file &gt; mplayer.bug
</screen>
</para>
</sect3>
</sect2>
</sect1>

</appendix>