2 <title>Troubleshooting / Reporting bugs
</title>
4 <sect1 id=
"troubleshooting">
5 <title>What to do if some program still doesn't work?
</title>
8 There are times when you've been trying everything, you even killed a cat
9 at full moon and ate it with rotten garlic and foul fish
10 while doing the Devil's Dance, yet nothing helped to make some damn
11 program work on some Wine version.
12 Don't despair, we're here to help you...
13 (in other words: how much do you want to pay ?)
17 <title>Run
"winecheck" to check your configuration
</title>
20 Run a Perl script called
<command>winecheck
</command>.
21 For details, please refer to the
<link
22 linkend=
"config-verify">Configuration section
</link>.
27 <title>Use different windows version settings
</title>
30 In several cases using
<link linkend=
"config-windows-versions">different windows version settings
</link> can help.
35 <title>Use different startup paths
</title>
38 This sometimes helps, too:
41 <command>wine prg.exe
</command>
43 <command>wine x:\\full\\path\\to\\prg.exe
</command>
48 <title>Fiddle with DLL configuration
</title>
51 Run with --debugmsg +loaddll to figure out which DLLs are
52 being used, and whether they're being loaded as native or
54 Then make sure you have proper native DLL files in your
55 configured C:\windows\system directory and fiddle with DLL
56 load order settings at command line or in config file.
61 <title>Check your system environment !
</title>
64 Just an idea: could it be that your Wine build/execution
65 environment is broken ?
67 Make sure that there are no problems whatsoever with the
69 that Wine depends on (gcc, glibc, X libraries, OpenGL (!), ...)
71 E.g. some people have strange failures to find stuff when
72 using
"wrong" header files for the
"right" libraries !!!
73 (which results in days of debugging to desperately try to find
74 out why that lowlevel function fails in a way that is completely
75 beyond imagination... ARGH !)
80 <title>Use different GUI (Window Manager) modes
</title>
83 Instruct Wine via config file to use either desktop mode,
84 managed mode or plain ugly
"normal" mode.
85 That can make one hell of a difference, too.
90 <title>Check your app !
</title>
93 Maybe your app is using some kind of copy protection ?
95 Many copy protections currently don't work on Wine.
96 Some might work in the future, though.
97 (the CD-ROM layer isn't really full-featured yet).
102 url=
"http://www.gamecopyworld.com">GameCopyWorld
</ulink>
103 and try to find a decent crack for your game that gets rid of
104 that ugly copy protection.
105 I hope you do have a legal copy of the program, though... :-)
110 <title>Check your Wine environment !
</title>
113 Running with or without a Windows partition can have a
116 Configure Wine to do the opposite of what you used to have.
118 Also, install DCOM98 or DCOM95. This can be very beneficial.
123 <title>Reconfigure Wine
</title>
126 Sometimes wine installation process changes and new versions of
127 Wine account on these changes.
128 This is especially true if your setup was created long time ago.
130 Rename your existing
<filename>~/.wine
</filename> directory
132 Use the setup process that's recommended for your Wine distribution
133 to create new configuration.
134 Use information in old
<filename>~/.wine
</filename>
135 directory as a reference.
136 For source wine distribution to configure Wine run
137 tools/wineinstall script as a user you want to do the configuration
139 This is a pretty safe operation. Later you can remove the new
140 <filename>~/.wine
</filename> directory and rename your old one back.
145 <title>Check out further information
</title>
148 There is a really good chance that someone has already tried
149 to do the same thing as you. You may find the
150 following resources helpful:
156 Search
<ulink url=
"http://appdb.winehq.com">WineHQ's
157 Application Database
</ulink> to check for any tips
158 relating to the program. If your specific version of
159 the program isn't listed you may find a different one
160 contains enough information to help you out.
165 <ulink url=
"http://www.frankscorner.org">Frank's Corner
</ulink>
166 contains a list of applications and detailed instructions
167 for setting them up. Further help can be found in the user
173 <ulink url=
"http://www.google.com">Google
</ulink> can be
174 useful depending on how you use it. You may
175 find it helpful to search
176 <ulink url=
"http://groups.google.com">Google Groups
</ulink>,
178 <ulink url=
"http://groups.google.com/groups?hl=en&lr=&ie=UTF-8&group=comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine
</ulink>
184 <ulink url=
"http://www.freenode.net">Freenode.net
</ulink>
185 hosts an IRC channel for Wine. You can access it by using
186 any IRC client such as Xchat. The settings you'll need are:
187 server = irc.freenode.net, port =
6667, and channel = #winehq
192 If you know you are missing a DLL, such as Visual Basic
193 Runtime, you may be able to find it at
194 <ulink url=
"http://www.dll-files.com/">www.dll-files.com
</ulink>
199 Wine's
<ulink url=
"http://www.winehq.com/site/forums#ml">mailing
200 lists
</ulink> may also help, especially wine-users. The
201 wine-devel list may be appropriate depending on the type of
202 problem you are experiencing. If you post to wine-devel you
203 should be prepared to do a little work to help diagnose the
204 problem. Read the section below to find out how to debug
205 the source of your problem.
210 If all else fails, you may wish to investigate commercial
211 versions of Wine to see if your application is supported.
219 <title>Debug it!
</title>
222 Finding the source of your problem is the next step to take.
223 There is a wide spectrum of possible problems
224 ranging from simple configurations issues to completely unimplemented
225 functionality in Wine. The next section will describe how to
226 file a bug report and how to begin debugging a crash. For more
227 information on using Wine's debugging facilities be sure to read
228 the Wine Developers Guide.
234 <sect1 id=
"bug-reporting">
235 <title>How To Report A Bug
</title>
238 Please report all bugs along any relevant information to
239 <ulink url=
"http://bugs.winehq.org/">Wine Bugzilla
</ulink>.
240 Please, search the Bugzilla database to check whether your problem
241 is already reported. If it is already reported please add
242 any relevant information to the original bug report.
246 <title>All Bug Reports
</title>
248 Some simple advice on making your bug report more useful
249 (and thus more likely to get answered and fixed):
254 Post as much relevant information as possible.
257 This means we need more information than a simple
"MS
258 Word crashes whenever I run it. Do you know why?"
259 Include at least the following information:
261 <itemizedlist spacing=
"compact">
264 Which version of Wine you're using (run
<command>wine -v
</command>)
269 The name of the Operating system you're using, what distribution (if
270 any), and what version. (i.e., Linux Red Hat
7.2)
275 Which compiler and version, (run
<command>gcc -v
</command>).
276 If you didn't compile wine then the name of the package and
277 where you got it from.
282 Windows version, if used with Wine.
283 Mention if you don't use Windows.
288 The name of the program you're trying to run, its version number,
289 and a URL for where the program can be obtained (if
295 The exact command line you used to start wine.
296 (i.e.,
<command>wine
"C:\Program Files\Test\program.exe"</command>).
301 The exact steps required to reproduce the bug.
306 Any other information you think may be relevant or
307 helpful, such as X server version in case of X
308 problems, libc version etc.
315 Re-run the program with the
<parameter>--debugmsg
316 +relay
</parameter> option (i.e.,
<command>wine
317 --debugmsg +relay sol.exe
</command>).
320 This will output additional information at the console
321 that may be helpful in debugging the program. It also
322 slows the execution of program. There are some cases where
323 the bug seems to disappear when
<parameter> +relay
324 </parameter> is used. Please mention that in the bug report.
330 <title>Crashes
</title>
332 If Wine crashes while running your program, it is
333 important that we have this information to have a chance
334 at figuring out what is causing the crash. This can put
335 out quite a lot (several MB) of information, though, so
336 it's best to output it to a file. When the
<prompt>Wine-dbg
></prompt>
337 prompt appears, type
<userinput>quit
</userinput>.
340 You might want to try
341 <parameter>+relay,+snoop
</parameter> instead of
342 <parameter>+relay
</parameter>, but please note that
343 <parameter>+snoop
</parameter> is pretty unstable and
344 often will crash earlier than a simple
345 <parameter>+relay
</parameter>! If this is the case, then
346 please use
<emphasis>only
</emphasis> <parameter>+relay
</parameter>!!
347 A bug report with a crash in
<parameter>+snoop
</parameter>
348 code is useless in most cases!
349 You can also turn on other parameters, depending on the nature
350 of the problem you are researching. See wine man page for full list
354 To get the trace output, use one of the following methods:
357 <title>The Easy Way
</title>
361 This method is meant to allow even a total novice to
362 submit a relevant trace log in the event of a crash.
365 Your computer
<emphasis>must
</emphasis> have perl on it
366 for this method to work. To find out if you have perl,
367 run
<command>which perl
</command>. If it returns something like
368 <filename>/usr/bin/perl
</filename>, you're in business.
369 Otherwise, skip on down to
"The Hard Way". If you aren't
370 sure, just keep on going. When you try to run the
371 script, it will become
<emphasis>very
</emphasis> apparent
372 if you don't have perl.
377 Change directory to
<filename><dirs to wine
>/tools
</filename>
382 Type in
<command>./bug_report.pl
</command> and follow
389 <ulink url=
"http://bugs.winehq.org/">Wine Bugzilla
</ulink>.
390 Please, search Bugzilla database to check whether your problem is
391 already found before posting a bug report.
392 Include your own detailed description of the problem with
393 relevant information. Attach the
"Nice Formatted Report"
394 to the submitted bug. Do not cut and paste the report
395 in the bug description - it is pretty big.
396 Keep the full debug output in case it will be needed by
403 <title>The Hard Way
</title>
405 It is likely that only the last
100 or so lines of the
406 trace are necessary to find out where the program crashes.
407 In order to get those last
100 lines we need to do the following
412 Redirect all the output of
<parameter> -debugmsg
</parameter>
418 Separate the last
100 lines to another file using
419 <command>tail
</command>.
424 This can be done using one of the following methods.
428 <term>all shells:
</term>
431 <prompt>$
</prompt>echo quit | wine -debugmsg +relay [other_options] program_name
>& filename.out;
432 <prompt>$
</prompt>tail -n
100 filename.out
> report_file
435 (This will print wine's debug messages only to the file
436 and then auto-quit. It's probably a good idea to use this
437 command, since wine prints out so many debug msgs that
438 they flood the terminal, eating CPU cycles.)
443 <term>tcsh and other csh-like shells:
</term>
446 <prompt>$
</prompt>wine -debugmsg +relay [other_options] program_name |& tee filename.out;
447 <prompt>$
</prompt>tail -n
100 filename.out
> report_file
452 <term>bash and other sh-like shells:
</term>
455 <prompt>$
</prompt>wine -debugmsg +relay [other_options] program_name
2>&
1 | tee filename.out;
456 <prompt>$
</prompt>tail -n
100 filename.out
> report_file
462 <filename>report_file
</filename> will now contain the
463 last hundred lines of the debugging output, including
464 the register dump and backtrace, which are the most
465 important pieces of information. Please do not delete
466 this part, even if you don't understand what it means.
470 <ulink url=
"http://bugs.winehq.org/">Wine Bugzilla
</ulink>.
471 You need to attach the output file
<filename>report_file
</filename>
472 from part
2). Along with the the relevant information
473 used to create it. Do not cut and paste the report
474 in the bug description - it is pretty big and it will
475 make a mess of the bug report.
476 If you do this, your chances of receiving some sort of
477 helpful response should be very good.
480 Please, search the Bugzilla database to check whether your problem
481 is already reported. If it is already reported attach the
482 output file
<filename>report_file
</filename> to the original
483 bug report and add any other relevant information.
490 <!-- Keep this comment at the end of the file
493 sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")