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