Mercurial > mplayer.hg
annotate DOCS/xml/en/bugreports.xml @ 20385:985accf8cf95
<replaceable> tags aren't needed in literal example
author | torinthiel |
---|---|
date | Mon, 23 Oct 2006 07:03:38 +0000 |
parents | 2c8c28415e89 |
children | c0687e92d463 |
rev | line source |
---|---|
9675 | 1 <?xml version="1.0" encoding="iso-8859-1"?> |
10913
49b1a67e7381
Add revision keyword to english xml files, to ease translation synchronization
lumag
parents:
10111
diff
changeset
|
2 <!-- $Revision$ --> |
9675 | 3 <appendix id="bugreports"> |
4 <title>How to report bugs</title> | |
5 <para> | |
6 Good bug reports are a very valuable contribution to the development of any | |
7 software project. But just like writing good software, good problem reports | |
8 involve some work. Please realize that most developers are extremely busy and | |
9 receive obscene amounts of email. So while your feedback is crucial in improving | |
11540 | 10 <application>MPlayer</application> and very much appreciated, please understand |
11 that you have to provide <emphasis role="bold">all</emphasis> of the information | |
12 we request and follow the instructions in this document closely. | |
9675 | 13 </para> |
18061
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
14 <sect1 id="bugreports_security"> |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
15 <title>Report security releated bugs</title> |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
16 <para> |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
17 In case you have found an exploitable bug and you would like to do the |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
18 right thing and let us fix it before you disclose it, we would be happy |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
19 to get your security advisory at |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
20 <ulink url="mailto:security@mplayerhq.hu">security@mplayerhq.hu</ulink>. |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
21 Please add [SECURITY] or [ADVISORY] in the subject. |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
22 Be sure that your report contains complete and detailed analysis of the bug. |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
23 Sending a fix is highly appreciated. |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
24 Please don't delay your report to write proof-of-concept exploit, you can |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
25 send that one with another mail. |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
26 </para> |
38e5974fa140
Explain how security issues should be reported, based on a patch by Ivann, featuring Reimar's suggestions
gpoirier
parents:
18059
diff
changeset
|
27 </sect1> |
9675 | 28 <sect1 id="bugreports_fix"> |
29 <title>How to fix bugs</title> | |
30 <para> | |
31 If you feel have the necessary skills you are invited to have a go at fixing the | |
32 bug yourself. Or maybe you already did that? Please read | |
33 <ulink url="../../tech/patches.txt">this short document</ulink> to find out how to | |
11540 | 34 get your code included in <application>MPlayer</application>. The people on the |
19709 | 35 <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-dev-eng">MPlayer-dev-eng</ulink> |
9675 | 36 mailing list will assist you if you have questions. |
37 </para> | |
38 </sect1> | |
17055 | 39 <sect1 id="bugreports_regression_test"> |
18599 | 40 <title>How to do regression testing using Subversion</title> |
17055 | 41 <para> |
42 A problem that can happen sometimes is 'it used to work before, now it | |
43 doesn't anymore...'. | |
44 Here is a step by step procedure to try to pinpoint when the problem | |
45 occurred. This is <emphasis role="bold">not</emphasis> for casual users. | |
46 </para> | |
47 <para> | |
18599 | 48 First, you'd need to fetch MPlayer's source tree from Subversion. |
17055 | 49 Instructions can be found at the bottom of |
17706
83c1acef76d5
New website structure, the /homepage subdirectory is gone.
diego
parents:
17055
diff
changeset
|
50 <ulink url="http://www.mplayerhq.hu/dload.html">this page</ulink>. |
17055 | 51 </para> |
52 <para> | |
18599 | 53 You will have now in the mplayer/ directory an image of the Subversion tree, on the |
17055 | 54 client side. |
55 Now update this image to the date you want: | |
56 <screen> | |
18599 | 57 cd mplayer/ |
58 svn update -r {"2004-08-23"} | |
17055 | 59 </screen> |
60 The date format is YYYY-MM-DD HH:MM:SS. | |
61 Using this date format ensure that you will be able to extract patches | |
62 according to the date at which they were committed, as in the | |
19679 | 63 <ulink url="http://lists.mplayerhq.hu/pipermail/mplayer-cvslog/">MPlayer-cvslog archive</ulink>. |
17055 | 64 </para> |
65 <para> | |
66 Now proceed as for a normal update: | |
67 <screen> | |
68 ./configure | |
69 make | |
70 </screen> | |
71 </para> | |
72 <para> | |
73 If any non-programmer reads this, the fastest method to get at the point | |
74 where the problem occurred is to use a binary search — that is, | |
18599 | 75 search the date of the breakage by repeatedly dividing the search |
17055 | 76 interval in half. |
77 For example, if the problem occurred in 2003, start at mid-year, then ask | |
78 "Is the problem already here?". | |
79 If yes, go back to the first of April; if not, go to the first of October, | |
80 and so on. | |
81 </para> | |
82 <para> | |
83 If you have lot of free hard disk space (a full compile currently takes | |
84 100 MB, and around 300-350 MB if debugging symbols are enabled), copy the | |
85 oldest known working version before updating it; this will save time if | |
86 you need to go back. | |
87 (It is usually necessary to run 'make distclean' before recompiling an | |
88 earlier version, so if you do not make a backup copy of your original | |
89 source tree, you will have to recompile everything in it when you come | |
90 back to the present.) | |
91 </para> | |
92 <para> | |
93 When you have found the day where the problem happened, continue the search | |
18599 | 94 using the mplayer-cvslog archive (sorted by date) and a more precise svn |
17055 | 95 update including hour, minute and second: |
96 <screen> | |
18599 | 97 svn update -r {"2004-08-23 15:17:25"} |
17055 | 98 </screen> |
99 This will allow you to easily find the exact patch that did it. | |
100 </para> | |
101 <para> | |
102 If you find the patch that is the cause of the problem, you have almost won; | |
103 report about it to the | |
104 <ulink url="http://bugzilla.mplayerhq.hu/">MPlayer Bugzilla</ulink> or | |
105 subscribe to | |
19709 | 106 <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-users">MPlayer-users</ulink> |
17055 | 107 and post it there. |
108 There is a chance that the author will jump in to suggest a fix. | |
109 You may also look hard at the patch until it is coerced to reveal where | |
110 the bug is :-). | |
111 </para> | |
112 </sect1> | |
9675 | 113 <sect1 id="bugreports_report"> |
114 <title>How to report bugs</title> | |
115 <para> | |
18599 | 116 First of all please try the latest Subversion version of <application>MPlayer</application> |
11540 | 117 as your bug might already be fixed there. Development moves extremely fast, |
118 most problems in official releases are reported within days or even hours, so | |
18599 | 119 please use <emphasis role="bold">only Subversion</emphasis> to report bugs. This |
120 includes binary packages of <application>MPlayer</application>. Subversion | |
11540 | 121 instructions can be found at the bottom of |
17706
83c1acef76d5
New website structure, the /homepage subdirectory is gone.
diego
parents:
17055
diff
changeset
|
122 <ulink url="http://www.mplayerhq.hu/dload.html">this page</ulink> or in |
9675 | 123 the README. If this did not help please refer to the list of |
124 <link linkend="bugs">known bugs</link> and the rest of the documentation. If your | |
125 problem is not known or not solvable by our instructions, then please report the bug. | |
126 </para> | |
127 | |
128 <para> | |
129 Please do not send bug reports privately to individual developers. This is | |
130 community work and thus there might be several people interested in it. Sometimes | |
131 other users already experienced your troubles and know how to circumvent a problem | |
11540 | 132 even if it is a bug in <application>MPlayer</application> code. |
9675 | 133 </para> |
134 | |
135 <para> | |
136 Please describe your problem in as much detail as possible. Do a little detective | |
137 work to narrow down the circumstances under which the problem occurs. Does the bug | |
138 only show up in certain situations? Is it specific to certain files or file types? | |
139 Does it occur with only one codec or is it codec independent? Can you reproduce it | |
140 with all output drivers? The more information you provide the better are our | |
141 chances at fixing your problem. Please do not forget to also include the valuable | |
142 information requested below, we will be unable to properly diagnose your problem | |
143 otherwise. | |
144 </para> | |
145 | |
146 <para> | |
147 An excellent and well written guide to asking questions in public forums is | |
9740 | 148 <ulink url="http://www.catb.org/~esr/faqs/smart-questions.html">How To Ask |
149 Questions The Smart Way</ulink> by <ulink url="http://www.catb.org/~esr/">Eric S. Raymond</ulink>. | |
9675 | 150 There is another called |
151 <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How to Report | |
152 Bugs Effectively</ulink> by <ulink url="http://www.chiark.greenend.org.uk/~sgtatham/">Simon Tatham</ulink>. | |
153 If you follow these guidelines you should be able to get help. But please | |
154 understand that we all follow the mailing lists voluntarily in our free time. We | |
155 are very busy and cannot guarantee that you will get a solution for your problem | |
156 or even an answer. | |
157 </para> | |
158 | |
159 </sect1> | |
160 | |
161 <sect1 id="bugreports_where"> | |
162 <title>Where to report bugs</title> | |
163 <para> | |
15029 | 164 Subscribe to the MPlayer-users mailing list: |
19709 | 165 <ulink url="http://lists.mplayerhq.hu/mailman/listinfo/mplayer-users"/> |
12622 | 166 and send your bug report to |
167 <ulink url="mailto:mplayer-users@mplayerhq.hu"/> where you can discuss it. | |
168 </para> | |
169 <para> | |
12695 | 170 If you prefer, you can use our brand-new |
12664 | 171 <ulink url="http://bugzilla.mplayerhq.hu/">Bugzilla</ulink> instead. |
9675 | 172 </para> |
173 <para> | |
10111 | 174 The language of this list is <emphasis role="bold">English</emphasis>. Please follow the standard |
9675 | 175 <ulink url="http://www.ietf.org/rfc/rfc1855.txt">Netiquette Guidelines</ulink> and |
10111 | 176 <emphasis role="bold">do not send HTML mail</emphasis> to any of our mailing lists. You will only get ignored or |
9675 | 177 banned. If you do not know what HTML mail is or why it is evil, read this |
178 <ulink url="http://expita.com/nomime.html">fine document</ulink>. It explains all | |
179 the details and has instructions for turning HTML off. Also note that we will not | |
180 individually CC (carbon-copy) people so it is a good idea to subscribe to actually | |
181 receive your answer. | |
182 </para> | |
183 </sect1> | |
184 | |
185 <sect1 id="bugreports_what"> | |
186 <title>What to report</title> | |
187 <para> | |
188 You may need to include log, configuration or sample files in your bug report. | |
189 If some of them are quite big then it is better to upload them to our | |
19581 | 190 <ulink url="ftp://upload.mplayerhq.hu/MPlayer/incoming/">FTP server</ulink> in a |
9675 | 191 compressed format (gzip and bzip2 preferred) and include only the path and file |
192 name in your bug report. Our mailing lists have a message size limit of 80k, if | |
193 you have something bigger you have to compress or upload it. | |
194 </para> | |
195 | |
196 <sect2 id="bugreports_system"> | |
197 <title>System Information</title> | |
198 <para> | |
199 <itemizedlist> | |
200 <listitem><para> | |
201 Your Linux distribution or operating system and version e.g.: | |
202 <itemizedlist> | |
203 <listitem><para>Red Hat 7.1</para></listitem> | |
204 <listitem><para>Slackware 7.0 + devel packs from 7.1 ...</para></listitem> | |
205 </itemizedlist> | |
206 </para></listitem> | |
207 <listitem><para> | |
208 kernel version: | |
209 <screen>uname -a</screen> | |
210 </para></listitem> | |
211 <listitem><para> | |
212 libc version: | |
213 <screen>ls -l /lib/libc[.-]*</screen> | |
214 </para></listitem> | |
215 <listitem><para> | |
216 gcc and ld versions: | |
217 <screen> | |
218 gcc -v | |
219 ld -v | |
220 </screen> | |
221 </para></listitem> | |
222 <listitem><para> | |
10111 | 223 binutils version: |
224 <screen> | |
225 as --version | |
226 </screen> | |
227 </para></listitem> | |
228 <listitem><para> | |
9675 | 229 If you have problems with fullscreen mode: |
230 <itemizedlist> | |
231 <listitem><para>Window manager type and version</para></listitem> | |
232 </itemizedlist> | |
233 </para></listitem> | |
234 <listitem><para> | |
235 If you have problems with XVIDIX: | |
236 <itemizedlist> | |
237 <listitem><para>X colour depth: | |
238 <screen>xdpyinfo | grep "depth of root"</screen> | |
239 </para></listitem> | |
240 </itemizedlist> | |
241 </para></listitem> | |
242 <listitem><para> | |
243 If only the GUI is buggy: | |
244 <itemizedlist> | |
245 <listitem><para>GTK version</para></listitem> | |
246 <listitem><para>GLIB version</para></listitem> | |
247 <listitem><para>libpng version</para></listitem> | |
248 <listitem><para>GUI situation in which the bug occurs</para></listitem> | |
249 </itemizedlist> | |
250 </para></listitem> | |
251 </itemizedlist> | |
252 </para> | |
253 </sect2> | |
254 | |
255 <sect2 id="bugreports_hardware"> | |
256 <title>Hardware and drivers</title> | |
257 <para> | |
258 <itemizedlist> | |
259 <listitem><para> | |
260 CPU info (this works on Linux only): | |
261 <screen>cat /proc/cpuinfo</screen> | |
262 </para></listitem> | |
263 <listitem><para> | |
264 Video card manufacturer and model, e.g.: | |
265 <itemizedlist> | |
266 <listitem><para>ASUS V3800U chip: nVidia TNT2 Ultra pro 32MB SDRAM</para></listitem> | |
267 <listitem><para>Matrox G400 DH 32MB SGRAM</para></listitem> | |
268 </itemizedlist> | |
269 </para></listitem> | |
270 <listitem><para> | |
271 Video driver type & version, e.g.: | |
272 <itemizedlist> | |
273 <listitem><para>X built-in driver</para></listitem> | |
274 <listitem><para>nVidia 0.9.623</para></listitem> | |
275 <listitem><para>Utah-GLX CVS 2001-02-17</para></listitem> | |
276 <listitem><para>DRI from X 4.0.3</para></listitem> | |
277 </itemizedlist> | |
278 </para></listitem> | |
279 <listitem><para> | |
280 Sound card type & driver, e.g.: | |
281 <itemizedlist> | |
282 <listitem><para>Creative SBLive! Gold with OSS driver from oss.creative.com</para></listitem> | |
283 <listitem><para>Creative SB16 with kernel OSS drivers</para></listitem> | |
284 <listitem><para>GUS PnP with ALSA OSS emulation</para></listitem> | |
285 </itemizedlist> | |
286 </para></listitem> | |
287 <listitem><para> | |
288 If in doubt include <command>lspci -vv</command> output on Linux systems. | |
289 </para></listitem> | |
290 </itemizedlist> | |
291 </para> | |
292 </sect2> | |
293 | |
294 <sect2 id="bugreports_configure"> | |
295 <title>Configure problems</title> | |
296 <para> | |
297 If you get errors while running <command>./configure</command>, or autodetection | |
298 of something fails, read <filename>configure.log</filename>. You may find the | |
299 answer there, for example multiple versions of the same library mixed on your | |
300 system, or you forgot to install the development package (those with the -dev | |
301 suffix). If you think there is a bug, include <filename>configure.log</filename> | |
302 in your bug report. | |
303 </para> | |
304 </sect2> | |
305 | |
18059 | 306 <sect2 id="bugreports_compilation"> |
9675 | 307 <title>Compilation problems</title> |
308 <para> | |
309 Please include these files: | |
310 <itemizedlist> | |
311 <listitem><para>config.h</para></listitem> | |
312 <listitem><para>config.mak</para></listitem> | |
313 </itemizedlist> | |
314 </para> | |
315 </sect2> | |
316 | |
317 <sect2 id="bugreports_playback"> | |
318 <title>Playback problems</title> | |
319 <para> | |
320 Please include the output of <application>MPlayer</application> at verbosity level | |
321 1, but remember to <emphasis role="bold">not truncate the output</emphasis> when | |
322 you paste it into your mail. The developers need all of the messages to properly | |
323 diagnose a problem. You can direct the output into a file like this: | |
324 <screen>mplayer -v <replaceable>options</replaceable> <replaceable>filename</replaceable> > mplayer.log 2>&1</screen> | |
325 </para> | |
326 | |
327 <para> | |
328 If your problem is specific to one or more files, then please upload the offender(s) to: | |
19581 | 329 <ulink url="ftp://upload.mplayerhq.hu/MPlayer/incoming/"/> |
9675 | 330 </para> |
331 | |
332 <para> | |
333 Also upload a small text file having the same base name as your file with a .txt | |
334 extension. Describe the problem you are having with the particular file there and | |
11540 | 335 include your email address as well as the output of <application>MPlayer</application> |
336 at verbosity level 1. Usually the first 1-5 MB of a file are enough to reproduce | |
337 the problem, but to be sure we ask you to: | |
9675 | 338 <screen>dd if=<replaceable>yourfile</replaceable> of=<replaceable>smallfile</replaceable> bs=1024k count=5</screen> |
339 It will take the first five megabytes of '<emphasis role="bold">your-file</emphasis>' | |
340 and write it to '<emphasis role="bold">small-file</emphasis>'. Then try again on | |
341 this small file and if the bug still shows up your sample is sufficient for us. | |
342 Please <emphasis role="bold">do not ever</emphasis> send such files via mail! | |
343 Upload it, and send only the path/filename of the file on the FTP-server. If the | |
344 file is accessible on the net, then sending the <emphasis role="bold">exact</emphasis> | |
345 URL is sufficient. | |
346 </para> | |
347 </sect2> | |
348 | |
349 <sect2 id="bugreports_crash"> | |
350 <title>Crashes</title> | |
351 <para> | |
352 You have to run <application>MPlayer</application> inside <command>gdb</command> | |
353 and send us the complete output or if you have a <filename>core</filename> dump of | |
354 the crash you can extract useful information from the Core file. Here's how: | |
355 </para> | |
356 | |
357 <sect3 id="bugreports_debug"> | |
358 <title>How to conserve information about a reproducible crash</title> | |
359 <para> | |
11540 | 360 Recompile <application>MPlayer</application> with debugging code enabled: |
9675 | 361 <screen> |
362 ./configure --enable-debug=3 | |
363 make | |
364 </screen> | |
11540 | 365 and then run <application>MPlayer</application> within gdb using: |
9675 | 366 <screen>gdb ./mplayer</screen> |
367 You are now within gdb. Type: | |
368 <screen>run -v <replaceable>options-to-mplayer</replaceable> <replaceable>filename</replaceable></screen> | |
369 and reproduce your crash. As soon as you did it, gdb will return you to the command | |
370 line prompt where you have to enter | |
371 <screen> | |
372 bt | |
373 disass $pc-32 $pc+32 | |
374 info all-registers | |
375 </screen> | |
376 </para> | |
377 </sect3> | |
378 | |
379 <sect3 id="bugreports_core"> | |
380 <title>How to extract meaningful information from a core dump</title> | |
381 <para> | |
11049 | 382 Create the following command file: |
9675 | 383 <screen> |
384 bt | |
385 disass $pc-32 $pc+32 | |
386 info all-registers | |
387 </screen> | |
11049 | 388 Then simply execute this command: |
9675 | 389 <screen>gdb mplayer --core=core -batch --command=<replaceable>command_file</replaceable> > mplayer.bug</screen> |
390 </para> | |
391 </sect3> | |
392 </sect2> | |
393 </sect1> | |
394 | |
395 <sect1 id="bugreports_advusers"> | |
396 <title>I know what I am doing...</title> | |
397 <para> | |
398 If you created a proper bug report following the steps above and you are confident | |
11540 | 399 it is a bug in <application>MPlayer</application>, not a compiler problem or broken |
400 file, you have already read the documentation and you could not find a solution, | |
15029 | 401 your sound drivers are OK, then you might want to subscribe to the MPlayer-advusers |
11540 | 402 list and send your bug report there to get a better and faster answer. |
9675 | 403 </para> |
404 | |
405 <para> | |
406 Please be advised that if you post newbie questions or questions answered in the | |
407 manual there, you will be ignored or flamed instead of getting an appropriate answer. | |
408 So do not flame us and subscribe to -advusers only if you really know what you are | |
11540 | 409 doing and feel like being an advanced <application>MPlayer</application> user or |
410 developer. If you meet these criteria it should not be difficult to find out how to subscribe... | |
9675 | 411 </para> |
412 | |
413 </sect1> | |
414 | |
415 </appendix> |