Hi all, - added troubleshooting section to Wine Users Guide (taken from Wine Troubleshooting Guide) - documented Windows/DOS version values (grrr !) - misc. other stuff -- Andreas Mohr Stauferstr. 6, D-71272 Renningen, Germany
Determining best CVS host... Using CVSROOT :pserver:cvs@cvs.winehq.com:/home/wine Index: documentation/bugs.sgml =================================================================== RCS file: /home/wine/wine/documentation/bugs.sgml,v retrieving revision 1.6 diff -u -r1.6 bugs.sgml --- documentation/bugs.sgml 24 Jul 2002 03:00:02 -0000 1.6 +++ documentation/bugs.sgml 29 Oct 2002 19:38:58 -0000 @@ -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> Index: documentation/configuring.sgml =================================================================== RCS file: /home/wine/wine/documentation/configuring.sgml,v retrieving revision 1.17 diff -u -r1.17 configuring.sgml --- documentation/configuring.sgml 19 Oct 2002 01:00:04 -0000 1.17 +++ documentation/configuring.sgml 29 Oct 2002 19:39:04 -0000 @@ -401,6 +401,8 @@ 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 @@ </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 @@ -1053,11 +1055,6 @@ <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 driver (USER part). Both of these are linked into the @@ -1076,24 +1073,10 @@ <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 @@ 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 @@ 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 @@ <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 @@ ®istry; + <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" = "<version string>"</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"="<version string>"</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 @@ <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 @@ 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> Index: documentation/installing.sgml =================================================================== RCS file: /home/wine/wine/documentation/installing.sgml,v retrieving revision 1.7 diff -u -r1.7 installing.sgml --- documentation/installing.sgml 24 Jul 2002 03:00:02 -0000 1.7 +++ documentation/installing.sgml 29 Oct 2002 19:39:06 -0000 @@ -176,7 +176,7 @@ 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 @@ <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 @@ it yourself, compile <filename>programs/regapi</filename>, and run: </para> - <screen> - <userinput>programs/regapi/regapi setValue < winedefault.reg</userinput> - </screen> + <screen> + <userinput>programs/regapi/regapi setValue < winedefault.reg</userinput> + </screen> </listitem> <listitem> <para> @@ -303,6 +310,32 @@ </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 @@ </sect2> <sect2> - <title>LINUX requirements:</title> + <title>Linux requirements</title> <orderedlist> <listitem> <para> Index: documentation/wine.man.in =================================================================== RCS file: /home/wine/wine/documentation/wine.man.in,v retrieving revision 1.42 diff -u -r1.42 wine.man.in --- documentation/wine.man.in 23 May 2002 19:35:18 -0000 1.42 +++ documentation/wine.man.in 29 Oct 2002 19:39:07 -0000 @@ -5,7 +5,7 @@ .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 @@ 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]]
