summaryrefslogtreecommitdiffstats
path: root/DOCS/bugreports.html
blob: cafc919476ede4b719f4898ed439f76ce5c2605b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>

<HEAD>
  <TITLE>Bug reporting - MPlayer - The Movie Player for Linux</TITLE>
  <LINK REL="stylesheet" TYPE="text/css" HREF="default.css">
  <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
</HEAD>

<BODY>


<H1><A NAME="B">Appendix B - How to report bugs</A></H1>

<P>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 MPlayer and very much appreciated, please understand that you
  have to provide <B>all</B> of the information we request and follow the
  instructions in this document closely.</P>


<H2>How to fix bugs</H2>

<P>If you feel have the necessary skills you are invited to have a go at fixing
  the bug yourself.  Or maybe you already did that?  Please read
  <A HREF="tech/patches.txt">this short document</A> to find out how to get
  your code included in MPlayer. The people on the
  <A HREF="http://mplayerhq.hu/mailman/listinfo/mplayer-dev-eng">mplayer-dev-eng</A>
  mailing list will assist you if you have questions.</P>


<H2>How to report bugs</H2>

<P>First of all please try the latest CVS version of MPlayer as your bug
  might already be fixed there. Development moves extremely fast, most problems
  in official releases are reported within days or even hours, so please use
  <B>only CVS</B> to report bugs. CVS instructions can be found at the bottom of
  <A HREF="http://www.mplayerhq.hu/homepage/dload.html">this page</A> or in the
  README. If this did not help please refer to
  <A HREF="documentation.html#known_bugs">the list of known bugs</A> and the
  rest of the documentation. If your problem is not known or not solvable by our
  instructions, then please report the bug.</P>

<P>Please do not send bug reports privately to individual developers.  This is
  community work and thus there might be several people interested in it.
  Sometimes other users already experienced your troubles and know how to
  circumvent a problem even if it is a bug in MPlayer code.</P>

<P>Please describe your problem in as much detail as possible. Do a little
  detective work to narrow down the circumstances under which the problem
  occurs. Does the bug only show up in certain situations? Is it specific to
  certain files or file types? Does it occur with only one codec or is it codec
  independent? Can you reproduce it with all output drivers? The more
  information you provide the better are our chances at fixing your problem.
  Please do not forget to also include the valuable information requested below,
  we will be unable to properly diagnose your problem otherwise.</P>

<P>An excellent and well written guide to asking questions in public forums is
  <A HREF="http://www.tuxedo.org/~esr/faqs/smart-questions.html">How To Ask Questions The Smart Way</A>
  by <A HREF="http://www.tuxedo.org/~esr/">Eric S. Raymond</A>. There is another
  called
  <A HREF="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report Bugs Effectively</A>
  by <A HREF="http://www.chiark.greenend.org.uk/~sgtatham/">Simon Tatham</A>. If
  you follow these guidelines you should be able to get help. But please
  understand that we all follow the mailing lists voluntarily in our free time.
  We are very busy and cannot guarantee that you will get a solution for your
  problem or even an answer.</P>


<H3>Where to report bugs?</H3>

<P>Subscribe to the mplayer-users mailing list:<BR>
  &nbsp;&nbsp;&nbsp;&nbsp;<A HREF="http://mplayerhq.hu/mailman/listinfo/mplayer-users">http://mplayerhq.hu/mailman/listinfo/mplayer-users</A><BR>
  and send your bug report to:<BR>
  &nbsp;&nbsp;&nbsp;&nbsp;<A HREF="mailto:mplayer-users@mplayerhq.hu">mplayer-users@mplayerhq.hu</A></P>

<P>The language of this list is <B>English</B>. Please follow the standard
  <A HREF="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</A> and
  <B>do not send HTML mail</B> 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 <A HREF="http://expita.com/nomime.html">fine document</A>. 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.</P>


<H3>What to report?</H3>

<H4>System Information:</H4>

<UL>
  <LI>Your Linux distribution or operating system and version e.g.:
    <UL>
      <LI>Red Hat 7.1</LI>
      <LI>Slackware 7.0 + devel packs from 7.1 ...</LI>
    </UL>
  </LI>
  <LI>kernel version:<BR>
      <CODE>uname -a</CODE></LI>
  <LI>libc version:<BR>
      <CODE>ls -l /lib/libc[.-]*</CODE></LI>
  <LI>X version:<BR>
      <CODE>X -version</CODE></LI>
  <LI>gcc and ld versions:<BR>
      <CODE>gcc -v<BR>
      ld -v</CODE></LI>
  <LI>binutils version:<BR>
      <CODE>as --version</CODE></LI>
  <LI>If you have problems with fullscreen mode:
    <UL>
      <LI>Window manager type and version</LI>
    </UL>
  </LI>
  <LI>If only the GUI is buggy:
    <UL>
      <LI>GTK version</LI>
      <LI>GLIB version</LI>
      <LI>libpng version</LI>
      <LI>GUI situation in which the bug occurs</LI>
    </UL>
  </LI>
</UL>


<H4>Hardware &amp; drivers:</H4>

<UL>
  <LI>CPU info (this works on Linux only):<BR>
    <CODE>cat /proc/cpuinfo</CODE></LI>
  <LI>Video card manufacturer and model, e.g.:
    <UL>
      <LI>ASUS V3800U chip: nVidia TNT2 Ultra pro 32MB SDRAM</LI>
      <LI>Matrox G400 DH 32MB SGRAM</LI>
    </UL>
  </LI>
  <LI>Video driver type &amp; version, e.g.:
    <UL>
      <LI>X built-in driver</LI>
      <LI>nVidia 0.9.623</LI>
      <LI>Utah-GLX CVS 2001-02-17</LI>
      <LI>DRI from X 4.0.3</LI>
    </UL>
  </LI>
  <LI>Sound card type &amp; driver, e.g.:
    <UL>
      <LI>Creative SBLive! Gold with OSS driver from oss.creative.com</LI>
      <LI>Creative SB16 with kernel OSS drivers</LI>
      <LI>GUS PnP with ALSA OSS emulation</LI>
    </UL>
  </LI>
  <LI>If in doubt include <CODE>lspci -vv</CODE> output on Linux systems.</LI>
</UL>


<H4>For compilation problems/errors</H4>

Please include these files:

<UL>
  <LI><CODE>config.h</CODE></LI>
  <LI><CODE>config.mak</CODE></LI>
</UL>

Only if compilation fails below one of these directories, include these files:

<UL>
  <LI><CODE>Gui/config.mak</CODE></LI>
  <LI><CODE>libvo/config.mak</CODE></LI>
  <LI><CODE>libao2/config.mak</CODE></LI>
</UL>


<H4>For configure problems</H4>

Include <CODE>configure.log</CODE>.


<H4>For playback problems</H4>

<P>Please include the output of MPlayer at verbosity level 1, but
  remember to <B>not truncate the output</B> 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:</P>

<P><CODE>&nbsp;&nbsp;&nbsp;&nbsp;mplayer -v [options] [filename] &gt; mplayer.log 2&gt;&amp;1</CODE></P>

<P>If your problem is specific to one or more files, then please upload the
  offender(s) to:</P>

<P>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="ftp://mplayerhq.hu/MPlayer/incoming/">ftp://mplayerhq.hu/MPlayer/incoming/</A></P>

<P>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 MPlayer 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:</P>

<P><CODE>&nbsp;&nbsp;&nbsp;&nbsp;dd if=yourfile of=smallfile bs=1024k count=5</CODE></P>

<P>It will take the  first five megabytes of <STRONG>'your-file'</STRONG> and
  write it to <STRONG>'small-file'</STRONG>. Then try again on this small file
  and if the bug still shows up your sample is sufficient for us. Please
  <STRONG>do not ever</STRONG> 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 <STRONG>exact</STRONG> URL is
  sufficient.</P>


<H4>For crashes</H4>

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

<H4>How to conserve information about a reproducible crash</H4>

Recompile MPlayer with debugging code enabled:

<P><CODE>&nbsp;&nbsp;&nbsp;&nbsp;./configure --enable-debug=3<BR>
  &nbsp;&nbsp;&nbsp;&nbsp;make</CODE></P>

and then run MPlayer within gdb using:

<P><CODE>&nbsp;&nbsp;&nbsp;&nbsp;gdb ./mplayer</CODE></P>

You are now within gdb. Type:

<P><CODE>&nbsp;&nbsp;&nbsp;&nbsp;run -v [options-to-mplayer] filename</code></P>

and reproduce your crash. As soon as you did it, gdb will
return you to the command line prompt where you have to enter

<P><CODE>&nbsp;&nbsp;&nbsp;&nbsp;bt<BR>
  &nbsp;&nbsp;&nbsp;&nbsp;disass $pc-32 $pc+32</CODE></P>


<H4>How to extract meaningful information from a core dump</H4>

<P>Please create the following command file:</P>

<P><CODE>disass $pc-32 $pc+32<BR>
  info all-registers</CODE></P>

<P>Then simply execute the following on your command line:</P>

<P>&nbsp;&nbsp;&nbsp;&nbsp;<CODE>gdb mplayer --core=core -batch --command=command_file &gt; mplayer.bug</CODE></P>


<H3>General note</H3>

<P>If something is quite big (logs for instance) then it is better to upload
  it to the FTP server in a compressed format (gzip and bzip2 preferred) and
  include only the path and filename in your bug report. Our mailing lists
  have a message size limit of 80k, if you have something bigger you have to
  compress or upload it.</P>


<H2>I know what I am doing...</H2>

<P>If you created a proper bug report following the steps above and you are
  confident it is a bug in MPlayer, not a compiler problem or broken
  file, you have already read the documentation and you could not find a
  solution, your sound drivers are OK, then you might want to subscribe to the
  mplayer-advusers list and send your bug report there to get a better and
  faster answer.<BR><BR> 
  Please be advised that if you post newbie questions or questions answered
  in the manual there, you will be ignored or flamed instead of getting an
  appropriate answer.<BR>
  So do not flame us and  subscribe to -advusers only if you really know
  what you are doing and feel like being an advanced MPlayer user or
  developer.  If you meet these criteria it should not be difficult to find
  out how to subscribe...</P>

</BODY>
</HTML>