- added troubleshooting section to Wine Users Guide (taken from Wine

Troubleshooting Guide)
- documented Windows/DOS version values (grrr !)
- misc. other stuff
This commit is contained in:
Andreas Mohr 2002-10-29 23:13:01 +00:00 committed by Alexandre Julliard
parent 6f6abac4f1
commit 70c82e8059
4 changed files with 363 additions and 60 deletions

View File

@ -1,5 +1,194 @@
<chapter id="bugs">
<title>Finding and Reporting Bugs</title>
<title>Troubleshooting / Reporting bugs</title>
<sect1 id="troubleshooting">
<title>What to do if some program still doesn't work ?</title>
<para>
There are times when you've been trying everything, you even killed a cat
at full moon and ate it with rotten garlic and foul fish
while doing the Devil's Dance, yet nothing helped to make some damn
program work on some Wine version.
Don't despair, we're here to help you...
(in other words: how much do you want to pay ?)
</para>
<sect2>
<title>Run "winecheck" to check your configuration</title>
<para>
Run a Perl script called <command>winecheck</command>, to be
found in Wine's tools/ directory.
The latest version can always be found at
<ulink
url="http://home.arcor.de/andi.mohr/download/winecheck">http://home.arcor.de/andi.mohr/download/winecheck</ulink>.
Make sure to run <command>chmod +x winecheck</command> first before
trying to execute it...
(or alternatively run it via <command>perl ./winecheck</command>)
The winecheck output will be a percentage score indicating Wine
configuration correctness.
Note that winecheck is only alpha, so it's not very complete or
100% accurate.
</para>
</sect2>
<sect2>
<title>Use different windows version settings</title>
<para>
In several cases using <link linkend="windows-versions">different windows version settings</link> can help.
</para>
</sect2>
<sect2>
<title>Use different startup paths</title>
<para>
This sometimes helps, too:
Try to use both
<command>wine prg.exe</command>
and
<command>wine x:\\full\\path\\to\\prg.exe</command>
</para>
</sect2>
<sect2>
<title>Fiddle with DLL configuration</title>
<para>
Run with --debugmsg +loaddll to figure out which DLLs are
being used, and whether they're being loaded as native or
builtin.
Then make sure you have proper native DLL files in your
configured C:\windows\system directory and fiddle with DLL
load order settings at command line or in config file.
</para>
</sect2>
<sect2>
<title>Check your system environment !</title>
<para>
Just an idea: could it be that your Wine build/execution
environment is broken ?
Make sure that there are no problems whatsoever with the
packages
that Wine depends on (gcc, glibc, X libraries, OpenGL (!), ...)
E.g. some people have strange failures to find stuff when
using "wrong" header files for the "right" libraries !!!
(which results in days of debugging to desperately try to find
out why that lowlevel function fails in a way that is completely
beyond imagination... ARGH !)
</para>
</sect2>
<sect2>
<title>Use different GUI (Window Manager) modes</title>
<para>
Instruct Wine via config file to use either desktop mode,
managed mode or plain ugly "normal" mode.
That can make one hell of a difference, too.
</para>
</sect2>
<sect2>
<title>Check your app !</title>
<para>
Maybe your app is using some kind of copy protection ?
Many copy protections currently don't work on Wine.
Some might work in the future, though.
(the CD-ROM layer isn't really full-featured yet).
</para>
<para>
Go to <ulink
url="http://www.gamecopyworld.com">GameCopyWorld</ulink>
and try to find a decent crack for your game that gets rid of
that ugly copy protection.
I hope you do have a legal copy of the program, though... :-)
</para>
</sect2>
<sect2>
<title>Check your Wine environment !</title>
<para>
Running with or without a Windows partition can have a
dramatic impact.
Configure Wine to do the opposite of what you used to have.
Also, install DCOM98 or DCOM95. This can be very beneficial.
</para>
</sect2>
<sect2>
<title>Reconfigure Wine</title>
<para>
Sometimes wine installation process changes and new versions of
Wine acccount on these changes.
This is especially true if your setup was created long time ago.
Rename your existing <filename>~/.wine</filename> directory
for backup purposes.
Use the setup process that's recommended for your Wine distribution
to create new configuration.
Use information in old <filename>~/.wine</filename>
directory as a reference.
For source wine distribution to configure Wine run
tools/wineinstall script as a user you want to do the configuration
for.
This is a pretty safe operation. Later you can remove the new
<filename>~/.wine</filename> directory and rename your old one back.
</para>
</sect2>
<sect2>
<title>Check out further information</title>
<para>
Check out the <ulink
url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> on WineHQ.
Go to <ulink url="http://groups.google.com">Google Groups</ulink>
and check whether some guys are smarter than you ;-)
(well, whether they found a solution to the problem, that is)
Go to <ulink url="http://appdb.codeweavers.com">WineHQ's
Application Database</ulink> and check whether
someone posted the vital config hint for your app.
If that doesn't help, then consider going to
irc.openprojects.net channel #WineHQ, posting to
news:comp.emulators.ms-windows.wine or mailing to the wine-users
(or maybe sometimes even wine-devel) mailing lists.
</para>
</sect2>
<sect2>
<title>Debug it!</title>
<para>
Have you used the Search feature of the <ulink
url="http://www.winehq.org/fom-meta/cache/19.html">Wine Troubleshooting Guide</ulink> ?? (i.e. are you sure there's no answer ?)
If you have, then try
<ulink url="http://www.winehq.org/fom-meta/cache/230.html">
The Perfect Enduser Wine Debugging Guide</ulink>, and of
course don't forget to read the Wine Developers Guide.
</para>
</sect2>
</sect1>
<sect1 id="bug-reporting">
<title>How To Report A Bug</title>
@ -8,7 +197,7 @@
Written by (???)
</para>
<para>
(Extracted from <filename>wine/documentation/bugreports</filename>)
(Originally extracted from <filename>wine/documentation/bugreports</filename>)
</para>
<para>

View File

@ -401,6 +401,8 @@ And here is a setup for Drive A, a generic floppy drive:
WARNING: if you use ttydrv here, then you won't be able to run
any Windows GUI programs. Thus this option is mainly interesting
for e.g. embedded use of Wine in web server scripts.
Note that ttydrv is still very lacking, so if it doesn't work,
resort to using "xvfb", a virtual X11 server.
</para>
<para>
<programlisting>"Printer" = "off|on"</programlisting> Tells wine
@ -929,7 +931,7 @@ OPTIONAL:
</para>
</sect3>
<sect3>
<sect3 id="appdefaults-section">
<title>The [AppDefaults] Section</title>
<para>
The section is used to overwrite certain settings of this file for a
@ -1052,11 +1054,6 @@ OPTIONAL:
<sect2>
<title>x11drv modes of operation</title>
<para>
<!-- FIXME: This is outdated -->
Note: This is now all done in the config file. Needs an update...
</para>
<para>
The x11drv driver consists of two conceptually distinct
pieces, the graphics driver (GDI part), and the windowing
@ -1075,25 +1072,11 @@ OPTIONAL:
</para>
<variablelist>
<varlistentry>
<term>Unmanaged/Normal</term>
<listitem>
<para>
The default. Window-manager-independent (any running
window manager is ignored completely). Window
decorations (title bars, borders, etc) are drawn by
Wine to look and feel like the real Windows. This is
compatible with applications that depend on being able
to compute the exact sizes of any such decorations, or
that want to draw their own.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Managed</term>
<listitem>
<para>
Specified by using the <literal>Managed</literal>
The default. Specified by using the <literal>Managed</literal>
wine config file option (see below).
Ordinary top-level frame windows with thick borders,
title bars, and system menus will be managed by your
@ -1101,8 +1084,24 @@ OPTIONAL:
better with the rest of your desktop, but may not
always work perfectly. (A rewrite of this mode of
operation, to make it more robust and less patchy, is
highly desirable, though, and is planned to be done
before the Wine 1.0 release.)
currently being done, though, and it's planned to be
finished before the Wine 1.0 release.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Unmanaged/Normal</term>
<listitem>
<para>
Window-manager-independent (any running
window manager is ignored completely). Window
decorations (title bars, borders, etc) are drawn by
Wine to look and feel like the real Windows. This is
compatible with applications that depend on being able
to compute the exact sizes of any such decorations, or
that want to draw their own.
Unmanaged mode is only used if both Managed and Desktop
are set to disabled.
</para>
</listitem>
</varlistentry>
@ -1124,8 +1123,8 @@ OPTIONAL:
applications can roam freely within this virtual
workspace and think they own it all, without
disturbing your other X apps.
Note: currently there's on desktop window for every
application; this will be fixed in the future.
Note: currently there's one desktop window for every
application; this will be fixed at some time.
</para>
</listitem>
</varlistentry>
@ -1296,17 +1295,11 @@ OPTIONAL:
<term>TextCP</term>
<listitem>
<para>
<!-- FIXME: To be documented -->
To be documented...
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>XVideoPort</term>
<listitem>
<para>
<!-- FIXME: To be documented -->
To be documented...
Codepage to be used for rendering the text in X11
output. Some sample values would be 437 (USA, Canada),
850 (Europe), 852 (Central/Eastern Europe), 855
(Cyrillic). For additional suitable values, see e.g. the Linux
kernel's codepage configuration page.
</para>
</listitem>
</varlistentry>
@ -1316,6 +1309,76 @@ OPTIONAL:
&registry;
<sect1 id="windows-versions">
<title>Setting the windows and DOS version value that's passed to
programs</title>
<para>
Written by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
Oct 18 2002
</para>
<para>
The windows and DOS version value a program gets e.g. by calling the
Windows function GetVersion() plays a very important role:
If your Wine installation for whatever reason fails to provide
to your program the correct version value that it expects,
then the program might assume some very bad things and fail (in
the worst case even silently !).
Fortunately Wine contains some more or less intelligent Windows
version guessing algorithm that will try to guess the Windows
version a program might expect and pass that one on to the
program.
Thus you should <emphasis>not</emphasis> lightly configure a version value, as this will be a "forced" value and thus turn out to be rather harmful to proper operation. In other words: only explicitly set a Windows version value in case Wine's own version detection was unable to provide the correct Windows version and the program fails.
</para>
<sect2>
<title>How to configure the Windows and DOS version value Wine
should return</title>
<para>
The version values can be configured in the wine config file in
the [Version] section.
</para>
<variablelist>
<varlistentry>
<term>"Windows" = "&lt;version string&gt;"</term>
<listitem>
<para>
default: none; chosen by semi-intelligent detection
mechanism based on DLL environment.
Used to specify which Windows version to return to
programs (forced value, overrides standard detection
mechanism !). Valid settings are e.g. "win31", "win95",
"win98", "win2k", "winxp".
Also valid as an
<link linkend="appdefaults-section">AppDefaults</link>
setting (recommended/preferred use).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>"DOS"="&lt;version string&gt;"</term>
<listitem>
<para>
Used to specify the DOS version that should be returned
to programs. Only takes effect in case Wine acts as
"win31" Windows version ! Common DOS version settings
include 6.22, 6.20, 6.00, 5.00, 4.00, 3.30, 3.10.
Also valid as an
<link linkend="appdefaults-section">AppDefaults</link>
setting (recommended/preferred use).
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="cdrom-labels">
<sect1info>
<authorgroup>
@ -1400,7 +1463,7 @@ OPTIONAL:
<para>
If you don't do that, then you should give fixed
<literal>"Label" =</literal> or <literal>"Serial" =</literal>
entries in <filename>~./wine/config</filename>, as Wine returns
entries in <filename>~/.wine/config</filename>, as Wine returns
these entries instead if no device is given. If they don't
exist, then Wine will return default values (label
<literal>Drive X</literal> and serial
@ -1896,6 +1959,24 @@ OPTIONAL:
directory. Just find out its directory by having a look at the Wine
config File variable "System" (which indicates the location of the
Windows system directory) and the associated drive entry.
Note that you probably shouldn't use NT-based native DLLs,
since Wine's NT API support is somewhat weaker than its Win9x
API support (thus leading to even worse compatibility with NT DLLs
than with a no-windows setup !), so better use Win9x native DLLs
instead or no native DLLs at all.
</para>
</sect2>
<sect2 id="dll-windows">
<title>Fetching native DLLs from a Windows CD</title>
<para>
Written by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
</para>
<para>
The Linux <command>cabextract</command> utility can be used to
extract native Windows .dll files from .cab files that are to be
found on many Windows installation CDs.
</para>
</sect2>
</sect1>

View File

@ -176,7 +176,7 @@ C:\ Root directory of primary disk drive
without having to install Windows on their machine. Wine
implements the functionality of the main DLLs usually
provided with Windows. Therefore, once Wine is finished, you
will not need to have windows installed to use Wine.
will not need to have Windows installed to use Wine.
</para>
<para>
Wine has already made enough progress that it may be possible
@ -187,25 +187,32 @@ C:\ Root directory of primary disk drive
<orderedlist>
<listitem>
<para>
Create empty <filename>C:\windows</filename>,
<filename>C:\windows\system</filename>,
<filename>C:\windows\Start Menu</filename>, and
<filename>C:\windows\Start Menu\Programs</filename>
Point <medialabel>[Drive C]</medialabel> in
<filename>~/.wine/config</filename> to the directory where you want
<filename>C:</filename> to be. Refer to the wine.conf man page
for more information.
The directory to be used for emulating a C: drive will be
the base directory for some Windows specific directories
created below.
Remember to use
<userinput>"Filesystem" = "win95"</userinput>!
</para>
</listitem>
<listitem>
<para>
Within the directory to be used for C:, create empty
<filename>windows</filename>,
<filename>windows/system</filename>,
<filename>windows/Start Menu</filename>, and
<filename>windows/Start Menu/Programs</filename>
directories. Do not point Wine to a
<filename>Windows</filename> directory full of old
installations and a messy registry. (Wine creates a
special registry in your <filename >home</filename>
directory, in <filename>$HOME/.wine/*.reg</filename>.
Perhaps you have to remove these files).
</para>
</listitem>
<listitem>
<para>
Point <medialabel>[Drive C]</medialabel> in
<filename>~/.wine/config</filename> to where you want
<filename>C:</filename> to be. Refer to the Wine man page
for more information. Remember to use
<userinput>"Filesystem" = "win95"</userinput>!
In one line:
mkdir -p windows windows/system windows/Start\ Menu windows/Start\ Menu/Programs
</para>
</listitem>
<listitem>
@ -215,9 +222,9 @@ C:\ Root directory of primary disk drive
it yourself, compile <filename>programs/regapi</filename>,
and run:
</para>
<screen>
<userinput>programs/regapi/regapi setValue &lt; winedefault.reg</userinput>
</screen>
<screen>
<userinput>programs/regapi/regapi setValue &lt; winedefault.reg</userinput>
</screen>
</listitem>
<listitem>
<para>
@ -303,6 +310,32 @@ C:\ Root directory of primary disk drive
</itemizedlist>
</sect1>
<sect1 id="with-windows">
<title>Installing Wine Using An Existing Windows Partition As Base</title>
<para>
Some people intend to use the data of an existing Windows partition
with Wine in order to gain some better compatibility or to run already
installed programs in a setup as original as possible.
Note that many Windows programs assume that they have full write
access to all windows directories.
This means that you either have to configure the Windows
partition mount point for write permission by your Wine user
(see <link linkend="vfat">Dealing with FAT/VFAT partitions</link>
on how to do that), or you'll have to copy over (some parts of) the Windows
partition content to a directory of a Unix partition and make
sure this directory structure is writable by your user.
We HIGHLY DISCOURAGE people from directly using a Windows partition with
write access as a base for Wine !! (some programs, notably
Explorer, corrupt large parts of the Windows partition in case
of an incorrect setup; you've been warned).
Not to mention that NTFS write support in Linux is still very
experimental and DANGEROUS (in case you're using an NT-based
Windows version using the NTFS file system).
Thus we advise you to go the Unix directory way.
</para>
</sect1>
<sect1 id="vfat">
<title>Dealing With FAT/VFAT Partitions</title>
<para>
@ -590,7 +623,7 @@ drwxrwxr-x 41 sle sle 16384 Dec 30 1998 windows</computeroutput>
</sect2>
<sect2>
<title>LINUX requirements:</title>
<title>Linux requirements</title>
<orderedlist>
<listitem>
<para>

View File

@ -5,7 +5,7 @@ wine \- run Windows programs on Unix
.SH SYNOPSIS
.BI "wine " "[wine_options] " "[--] " "program " "[arguments ... ]"
.PP
For instructions on passing arguments to Windows programs, please see the
For instructions on passing arguments to Windows programs, please see the
.B
PROGRAM/ARGUMENTS
section of the man page.
@ -39,8 +39,8 @@ using none at all or the ones from older Windows versions.
A large percentage of the API has been implemented,
although there are still several major pieces of work left to do.
.SH REQUIREMENTS AND INSTALLATION
Read the README file in the Wine source distribution to know what Wine
requires and how it is installed from source.
Read the README file in the Wine source distribution and the wine.conf
man page to know what Wine requires and how it is installed from source.
.SH OPTIONS
.TP
.I --debugmsg [xxx]#name[,[xxx1]#name1][,<+|->relay=yyy1[:yyy2]]