9675
|
1 <?xml version="1.0" encoding="iso-8859-1"?>
|
|
2 <appendix id="bugreports">
|
|
3 <title>How to report bugs</title>
|
|
4 <para>
|
|
5 Good bug reports are a very valuable contribution to the development of any
|
|
6 software project. But just like writing good software, good problem reports
|
|
7 involve some work. Please realize that most developers are extremely busy and
|
|
8 receive obscene amounts of email. So while your feedback is crucial in improving
|
|
9 MPlayer and very much appreciated, please understand that you have to provide
|
|
10 <emphasis role="bold">all</emphasis> of the information we request and follow
|
|
11 the instructions in this document closely.
|
|
12 </para>
|
|
13 <sect1 id="bugreports_fix">
|
|
14 <title>How to fix bugs</title>
|
|
15 <para>
|
|
16 If you feel have the necessary skills you are invited to have a go at fixing the
|
|
17 bug yourself. Or maybe you already did that? Please read
|
|
18 <ulink url="../../tech/patches.txt">this short document</ulink> to find out how to
|
|
19 get your code included in MPlayer. The people on the
|
|
20 <ulink url="http://mplayerhq.hu/mailman/listinfo/mplayer-dev-eng">mplayer-dev-eng</ulink>
|
|
21 mailing list will assist you if you have questions.
|
|
22 </para>
|
|
23 </sect1>
|
|
24 <sect1 id="bugreports_report">
|
|
25 <title>How to report bugs</title>
|
|
26 <para>
|
|
27 First of all please try the latest CVS version of MPlayer as your bug might
|
|
28 already be fixed there. Development moves extremely fast, most problems in
|
|
29 official releases are reported within days or even hours, so please use
|
|
30 <emphasis role="bold">only CVS</emphasis> to report bugs. This includes
|
|
31 binary packages of MPlayer. CVS instructions can be found at the bottom of
|
|
32 <ulink url="http://www.mplayerhq.hu/homepage/dload.html">this page</ulink> or in
|
|
33 the README. If this did not help please refer to the list of
|
|
34 <link linkend="bugs">known bugs</link> and the rest of the documentation. If your
|
|
35 problem is not known or not solvable by our instructions, then please report the bug.
|
|
36 </para>
|
|
37
|
|
38 <para>
|
|
39 Please do not send bug reports privately to individual developers. This is
|
|
40 community work and thus there might be several people interested in it. Sometimes
|
|
41 other users already experienced your troubles and know how to circumvent a problem
|
|
42 even if it is a bug in MPlayer code.
|
|
43 </para>
|
|
44
|
|
45 <para>
|
|
46 Please describe your problem in as much detail as possible. Do a little detective
|
|
47 work to narrow down the circumstances under which the problem occurs. Does the bug
|
|
48 only show up in certain situations? Is it specific to certain files or file types?
|
|
49 Does it occur with only one codec or is it codec independent? Can you reproduce it
|
|
50 with all output drivers? The more information you provide the better are our
|
|
51 chances at fixing your problem. Please do not forget to also include the valuable
|
|
52 information requested below, we will be unable to properly diagnose your problem
|
|
53 otherwise.
|
|
54 </para>
|
|
55
|
|
56 <para>
|
|
57 An excellent and well written guide to asking questions in public forums is
|
|
58 <ulink url="http://www.tuxedo.org/~esr/faqs/smart-questions.html">How To Ask
|
|
59 Questions The Smart Way</ulink> by <ulink url="http://www.tuxedo.org/~esr/">Eric S. Raymond</ulink>.
|
|
60 There is another called
|
|
61 <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report
|
|
62 Bugs Effectively</ulink> by <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/">Simon Tatham</ulink>.
|
|
63 If you follow these guidelines you should be able to get help. But please
|
|
64 understand that we all follow the mailing lists voluntarily in our free time. We
|
|
65 are very busy and cannot guarantee that you will get a solution for your problem
|
|
66 or even an answer.
|
|
67 </para>
|
|
68
|
|
69 </sect1>
|
|
70
|
|
71 <sect1 id="bugreports_where">
|
|
72 <title>Where to report bugs</title>
|
|
73 <para>
|
|
74 Subscribe to the mplayer-users mailing list:
|
|
75 <ulink url="http://mplayerhq.hu/mailman/listinfo/mplayer-users"/>
|
|
76 and send your bug report to:
|
|
77 <ulink url="mailto:mplayer-users@mplayerhq.hu"/>
|
|
78 </para>
|
|
79 <para>
|
|
80 The language of this list is English. Please follow the standard
|
|
81 <ulink url="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</ulink> and
|
|
82 do not send HTML mail to any of our mailing lists. You will only get ignored or
|
|
83 banned. If you do not know what HTML mail is or why it is evil, read this
|
|
84 <ulink url="http://expita.com/nomime.html">fine document</ulink>. It explains all
|
|
85 the details and has instructions for turning HTML off. Also note that we will not
|
|
86 individually CC (carbon-copy) people so it is a good idea to subscribe to actually
|
|
87 receive your answer.
|
|
88 </para>
|
|
89 </sect1>
|
|
90
|
|
91 <sect1 id="bugreports_what">
|
|
92 <title>What to report</title>
|
|
93 <para>
|
|
94 You may need to include log, configuration or sample files in your bug report.
|
|
95 If some of them are quite big then it is better to upload them to our
|
|
96 <ulink url="ftp://mplayerhq.hu/MPlayer/incoming/">FTP server</ulink> in a
|
|
97 compressed format (gzip and bzip2 preferred) and include only the path and file
|
|
98 name in your bug report. Our mailing lists have a message size limit of 80k, if
|
|
99 you have something bigger you have to compress or upload it.
|
|
100 </para>
|
|
101
|
|
102 <sect2 id="bugreports_system">
|
|
103 <title>System Information</title>
|
|
104 <para>
|
|
105 <itemizedlist>
|
|
106 <listitem><para>
|
|
107 Your Linux distribution or operating system and version e.g.:
|
|
108 <itemizedlist>
|
|
109 <listitem><para>Red Hat 7.1</para></listitem>
|
|
110 <listitem><para>Slackware 7.0 + devel packs from 7.1 ...</para></listitem>
|
|
111 </itemizedlist>
|
|
112 </para></listitem>
|
|
113 <listitem><para>
|
|
114 kernel version:
|
|
115 <screen>uname -a</screen>
|
|
116 </para></listitem>
|
|
117 <listitem><para>
|
|
118 libc version:
|
|
119 <screen>ls -l /lib/libc[.-]*</screen>
|
|
120 </para></listitem>
|
|
121 <listitem><para>
|
|
122 gcc and ld versions:
|
|
123 <screen>
|
|
124 gcc -v
|
|
125 ld -v
|
|
126 </screen>
|
|
127 </para></listitem>
|
|
128 <listitem><para>
|
|
129 If you have problems with fullscreen mode:
|
|
130 <itemizedlist>
|
|
131 <listitem><para>Window manager type and version</para></listitem>
|
|
132 </itemizedlist>
|
|
133 </para></listitem>
|
|
134 <listitem><para>
|
|
135 If you have problems with XVIDIX:
|
|
136 <itemizedlist>
|
|
137 <listitem><para>X colour depth:
|
|
138 <screen>xdpyinfo | grep "depth of root"</screen>
|
|
139 </para></listitem>
|
|
140 </itemizedlist>
|
|
141 </para></listitem>
|
|
142 <listitem><para>
|
|
143 If only the GUI is buggy:
|
|
144 <itemizedlist>
|
|
145 <listitem><para>GTK version</para></listitem>
|
|
146 <listitem><para>GLIB version</para></listitem>
|
|
147 <listitem><para>libpng version</para></listitem>
|
|
148 <listitem><para>GUI situation in which the bug occurs</para></listitem>
|
|
149 </itemizedlist>
|
|
150 </para></listitem>
|
|
151 </itemizedlist>
|
|
152 </para>
|
|
153 </sect2>
|
|
154
|
|
155 <sect2 id="bugreports_hardware">
|
|
156 <title>Hardware and drivers</title>
|
|
157 <para>
|
|
158 <itemizedlist>
|
|
159 <listitem><para>
|
|
160 CPU info (this works on Linux only):
|
|
161 <screen>cat /proc/cpuinfo</screen>
|
|
162 </para></listitem>
|
|
163 <listitem><para>
|
|
164 Video card manufacturer and model, e.g.:
|
|
165 <itemizedlist>
|
|
166 <listitem><para>ASUS V3800U chip: nVidia TNT2 Ultra pro 32MB SDRAM</para></listitem>
|
|
167 <listitem><para>Matrox G400 DH 32MB SGRAM</para></listitem>
|
|
168 </itemizedlist>
|
|
169 </para></listitem>
|
|
170 <listitem><para>
|
|
171 Video driver type & version, e.g.:
|
|
172 <itemizedlist>
|
|
173 <listitem><para>X built-in driver</para></listitem>
|
|
174 <listitem><para>nVidia 0.9.623</para></listitem>
|
|
175 <listitem><para>Utah-GLX CVS 2001-02-17</para></listitem>
|
|
176 <listitem><para>DRI from X 4.0.3</para></listitem>
|
|
177 </itemizedlist>
|
|
178 </para></listitem>
|
|
179 <listitem><para>
|
|
180 Sound card type & driver, e.g.:
|
|
181 <itemizedlist>
|
|
182 <listitem><para>Creative SBLive! Gold with OSS driver from oss.creative.com</para></listitem>
|
|
183 <listitem><para>Creative SB16 with kernel OSS drivers</para></listitem>
|
|
184 <listitem><para>GUS PnP with ALSA OSS emulation</para></listitem>
|
|
185 </itemizedlist>
|
|
186 </para></listitem>
|
|
187 <listitem><para>
|
|
188 If in doubt include <command>lspci -vv</command> output on Linux systems.
|
|
189 </para></listitem>
|
|
190 </itemizedlist>
|
|
191 </para>
|
|
192 </sect2>
|
|
193
|
|
194 <sect2 id="bugreports_configure">
|
|
195 <title>Configure problems</title>
|
|
196 <para>
|
|
197 If you get errors while running <command>./configure</command>, or autodetection
|
|
198 of something fails, read <filename>configure.log</filename>. You may find the
|
|
199 answer there, for example multiple versions of the same library mixed on your
|
|
200 system, or you forgot to install the development package (those with the -dev
|
|
201 suffix). If you think there is a bug, include <filename>configure.log</filename>
|
|
202 in your bug report.
|
|
203 </para>
|
|
204 </sect2>
|
|
205
|
|
206 <sect2 id="bugreports_conpilation">
|
|
207 <title>Compilation problems</title>
|
|
208 <para>
|
|
209 Please include these files:
|
|
210 <itemizedlist>
|
|
211 <listitem><para>config.h</para></listitem>
|
|
212 <listitem><para>config.mak</para></listitem>
|
|
213 </itemizedlist>
|
|
214 Only if compilation fails below one of these directories, include these files:
|
|
215 <itemizedlist>
|
|
216 <listitem><para>Gui/config.mak</para></listitem>
|
|
217 <listitem><para>libvo/config.mak</para></listitem>
|
|
218 <listitem><para>libao2/config.mak</para></listitem>
|
|
219 </itemizedlist>
|
|
220 </para>
|
|
221 </sect2>
|
|
222
|
|
223 <sect2 id="bugreports_playback">
|
|
224 <title>Playback problems</title>
|
|
225 <para>
|
|
226 Please include the output of <application>MPlayer</application> at verbosity level
|
|
227 1, but remember to <emphasis role="bold">not truncate the output</emphasis> when
|
|
228 you paste it into your mail. The developers need all of the messages to properly
|
|
229 diagnose a problem. You can direct the output into a file like this:
|
|
230 <screen>mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> > mplayer.log 2>&1</screen>
|
|
231 </para>
|
|
232
|
|
233 <para>
|
|
234 If your problem is specific to one or more files, then please upload the offender(s) to:
|
|
235 <ulink url="ftp://mplayerhq.hu/MPlayer/incoming/"/>
|
|
236 </para>
|
|
237
|
|
238 <para>
|
|
239 Also upload a small text file having the same base name as your file with a .txt
|
|
240 extension. Describe the problem you are having with the particular file there and
|
|
241 include your email address as well as the output of MPlayer at verbosity level 1.
|
|
242 Usually the first 1-5 MB of a file are enough to reproduce the problem, but to be
|
|
243 sure we ask you to:
|
|
244 <screen>dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5</screen>
|
|
245 It will take the first five megabytes of '<emphasis role="bold">your-file</emphasis>'
|
|
246 and write it to '<emphasis role="bold">small-file</emphasis>'. Then try again on
|
|
247 this small file and if the bug still shows up your sample is sufficient for us.
|
|
248 Please <emphasis role="bold">do not ever</emphasis> send such files via mail!
|
|
249 Upload it, and send only the path/filename of the file on the FTP-server. If the
|
|
250 file is accessible on the net, then sending the <emphasis role="bold">exact</emphasis>
|
|
251 URL is sufficient.
|
|
252 </para>
|
|
253 </sect2>
|
|
254
|
|
255 <sect2 id="bugreports_crash">
|
|
256 <title>Crashes</title>
|
|
257 <para>
|
|
258 You have to run <application>MPlayer</application> inside <command>gdb</command>
|
|
259 and send us the complete output or if you have a <filename>core</filename> dump of
|
|
260 the crash you can extract useful information from the Core file. Here's how:
|
|
261 </para>
|
|
262
|
|
263 <sect3 id="bugreports_debug">
|
|
264 <title>How to conserve information about a reproducible crash</title>
|
|
265 <para>
|
|
266 Recompile MPlayer with debugging code enabled:
|
|
267 <screen>
|
|
268 ./configure --enable-debug=3
|
|
269 make
|
|
270 </screen>
|
|
271 and then run MPlayer within gdb using:
|
|
272 <screen>gdb ./mplayer</screen>
|
|
273 You are now within gdb. Type:
|
|
274 <screen>run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable></screen>
|
|
275 and reproduce your crash. As soon as you did it, gdb will return you to the command
|
|
276 line prompt where you have to enter
|
|
277 <screen>
|
|
278 bt
|
|
279 disass $pc-32 $pc+32
|
|
280 info all-registers
|
|
281 </screen>
|
|
282 </para>
|
|
283 </sect3>
|
|
284
|
|
285 <sect3 id="bugreports_core">
|
|
286 <title>How to extract meaningful information from a core dump</title>
|
|
287 <para>
|
|
288 Please create the following command file:
|
|
289 <screen>
|
|
290 bt
|
|
291 disass $pc-32 $pc+32
|
|
292 info all-registers
|
|
293 </screen>
|
|
294 Then simply execute the following on your command line:
|
|
295 <screen>gdb mplayer --core=core -batch --command=<replaceable>command_file</replaceable> > mplayer.bug</screen>
|
|
296 </para>
|
|
297 </sect3>
|
|
298 </sect2>
|
|
299 </sect1>
|
|
300
|
|
301 <sect1 id="bugreports_advusers">
|
|
302 <title>I know what I am doing...</title>
|
|
303 <para>
|
|
304 If you created a proper bug report following the steps above and you are confident
|
|
305 it is a bug in MPlayer, not a compiler problem or broken file, you have already
|
|
306 read the documentation and you could not find a solution, your sound drivers are
|
|
307 OK, then you might want to subscribe to the mplayer-advusers list and send your
|
|
308 bug report there to get a better and faster answer.
|
|
309 </para>
|
|
310
|
|
311 <para>
|
|
312 Please be advised that if you post newbie questions or questions answered in the
|
|
313 manual there, you will be ignored or flamed instead of getting an appropriate answer.
|
|
314 So do not flame us and subscribe to -advusers only if you really know what you are
|
|
315 doing and feel like being an advanced MPlayer user or developer. If you meet these
|
|
316 criteria it should not be difficult to find out how to subscribe...
|
|
317 </para>
|
|
318
|
|
319 </sect1>
|
|
320
|
|
321 </appendix>
|