"Fossies" - the Fresh Open Source Software Archive
Member "wine-docs-1.8/en/wineusr-configuring.sgml" (25 Dec 2015, 38519 Bytes) of package /linux/misc/old/wine-docs-1.8.tar.gz:
As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
See also the latest Fossies "Diffs"
side-by-side code changes report for "wineusr-configuring.sgml": 1.6_vs_1.8
1 <chapter id="config-wine-main">
2 <title>Configuring Wine</title>
4 Most of the most common configuration changes can be done with the
5 <command>winecfg</command> tool. We'll go through an easy, step-by-step introduction
6 to <command>winecfg</command> and outline the options available.
7 In the next section we'll go over more advanced changes you can make
8 using <command>regedit</command> as well as provide a complete reference to all Wine
9 configuration settings. Finally, some things you might want to
10 configure fall out of the scope of <command>winecfg</command> and
11 <command>regedit</command>, and we'll go over those.
13 <sect1 id="using-winecfg">
14 <title>Using Winecfg</title>
16 In the past, Wine used a special configuration file that could be
17 found in <filename>~/.wine/config</filename>. If you are still using
18 a version of Wine that references this file (older than June, 2005)
19 you should upgrade before doing anything else. All settings are now
20 stored directly in the registry and accessed by Wine when it starts.
23 Winecfg should have been installed on your computer along with the
24 rest of the Wine programs. If you can't figure out how to start it,
25 try running <command>winecfg</command>.
28 When the program starts you'll notice there are tabs along the top
29 of the window for:
48 Desktop Integration
69 Changing settings in the
70 <guilabel>Applications</guilabel> and <guilabel>Libraries</guilabel>
71 tabs will have the most impact on getting an application to run. The
72 other settings focus on getting Wine itself to behave the way
73 you want it to.
76 Note: The <guilabel>Applications</guilabel>, <guilabel>Libraries</guilabel>, and
77 <guilabel>Graphics</guilabel> tabs are linked together! If you have <quote>Default
78 Settings</quote> selected under <guilabel>Applications</guilabel>, all of the changes made
79 within the <guilabel>Libraries</guilabel> and <guilabel>Graphics</guilabel> tabs will
80 be changed for all applications. If you've configured a specific application under the
81 <guilabel>Applications</guilabel> tab and have it selected, then any changes made in
82 <guilabel>Libraries</guilabel> or <guilabel>Graphics</guilabel> will affect only that
83 application. This allows for custom settings for specific applications.
85 <sect2 id="config-windows-versions">
86 <title>Application Settings</title>
88 Wine has the ability to mimic the behavior of different versions of
89 Windows. In general, the biggest difference is whether Wine
90 behaves as a Win9x version or an NT version. Some applications
91 require a specific behavior in order to function and changing
92 this setting may cause a buggy app to work. Wine default Windows version
93 is Windows XP. Some applications may perform better if you
94 choose Windows 98.
97 Within the tab you'll notice there is a
98 <emphasis>Default Settings</emphasis> entry. If you select that
99 you'll see the current default <emphasis>Windows Version</emphasis>
100 for all applications. A troublesome application
101 is best configured separately from the Default Settings. To do that:
105 Click on the <guibutton>Add application</guibutton> button.
110 Browse until you locate the executable.
115 After it's been added you can choose the specific Windows
116 version Wine will emulate for that application.
123 <title>Libraries Settings</title>
125 Likewise, some applications require specific libraries in order
126 to run. Wine reproduces the Windows system libraries (so-called
127 native DLLs) with completely custom versions designed to
128 function exactly the same way but without requiring licenses
129 from Microsoft. Wine has many known deficiencies in its
130 built-in versions, but in many instances the functionality
131 is sufficient. Using only builtin DLLs ensures that your
132 system is Microsoft-free. However, Wine has the ability to
133 load native Windows DLLs.
135 <sect3 id="winecfg-dll-overrides">
136 <title>DLL Overrides</title>
138 It's not always possible to run an application on builtin
139 DLLs, so sometimes native versions will be recommended as
140 a workaround for a specific problem.
141 Some may be directly copied to the directory configured
142 as <filename class="directory">c:\windows\system32</filename> (more on that in
143 the drives section) while others may require an installer, see
144 the next section on <command>winetricks</command>.
145 Native versions of these DLLs do not work:
146 <filename class="libraryfile">kernel32.dll</filename>,
147 <filename class="libraryfile">gdi32.dll</filename>,
148 <filename class="libraryfile">user32.dll</filename>,
149 and <filename class="libraryfile">ntdll.dll</filename>. These libraries require
150 low-level Windows kernel access that simply doesn't exist
151 within Wine.
154 With that in mind, once you've copied the DLL you just need to
155 tell Wine to try to use it. You can configure Wine to choose
156 between native and builtin DLLs at two different levels.
157 If you have <emphasis>Default Settings</emphasis> selected
158 in the <guilabel>Applications</guilabel> tab, the changes you
159 make will affect all applications. Or, you can override the
160 global settings on a per-application level by adding and
161 selecting an application in the <guilabel>Applications</guilabel> tab.
164 To add an override for <filename class="libraryfile">FOO.DLL</filename>, enter
165 <userinput>FOO</userinput> into the box
166 labeled <guilabel>New override for library:</guilabel> and
167 click on the <guibutton>Add</guibutton> button. To change how
168 the DLL behaves, select it within the <guilabel>Existing
169 overrides:</guilabel> box and choose <guibutton>Edit</guibutton>.
170 By default the new load order will be native Windows libraries
171 before Wine builtin ones (<emphasis>Native then
172 Builtin</emphasis>). You can also choose native only, builtin
173 only, or disable it altogether.
176 DLLs usually get loaded in the following order:
180 The directory the program was started from.
185 The current directory.
190 The Windows system directory.
195 The Windows directory.
200 The <envar>PATH</envar> variable directories.
207 <title>Notes About System or Missing DLLs</title>
209 There are of course DLLs that Wine does not currently implement
210 very well (or at all).
213 In case Wine complains about a missing DLL, you should check whether
214 this file is a publicly available DLL or a custom DLL belonging
215 to your program. In the latter case, check that you have installed
216 your program correctly.
219 Most often applications will assume that a required redistributable
220 package has already been installed and subsequently fail to run when
221 the required dependencies are not met. For example:
224 err:module:import_dll Library MFC42.DLL (which is needed by L"C:\\Program Files\\Foo\\Bar.dll") not found
227 Redistributable packages which install the necessary runtimes can
228 be obtained through the use of <ulink
229 url="http://wiki.winehq.org/winetricks">winetricks</ulink>. Note
230 these components are subject to their own
231 license and are not part of the Wine project. You should refer to
232 the application's <ulink url="http://appdb.winehq.org">AppDB</ulink>
233 entry for advice on what is required.
238 <title>Graphics Settings</title>
240 There are basically five different graphics settings you
241 can configure. For most people the defaults are fine.
244 The first setting primarily affect games and is somewhat
245 self-explanatory. You can prevent the mouse from leaving the
246 window of a full-screen program (e.g. a game) and the default
247 is to not have that box checked. That is mostly needed when using
248 a virtual desktop.
251 You may find it helpful to tick <guilabel>Emulate a virtual desktop</guilabel>.
252 In this case, all programs will run in a separate window. You
253 may find this useful as a way to test buggy games that change
254 (possibly unsuccessfully) the screen resolution. Confining them
255 to a window can allow for more control over them at the possible
256 expense of decreased usability. Sizes you might want to try are
257 800x600 (the default) or 1024x768.
261 <title>Drive Settings</title>
263 Windows requires a fairly rigid drive configuration that Wine
264 imitates. Most people are familiar with the standard notation
265 of the <filename class="devicefile">A:</filename> drive representing the floppy disk,
266 the <filename class="devicefile">C:</filename>
267 drive representing the primary system disk, etc. Wine uses
268 the same concept and maps those drives to the underlying native
271 Wine drive configuration is relatively simple.
272 In <command>winecfg</command> under the <guilabel>Drives</guilabel> tab you'll
273 see buttons to add and remove available drives.
274 When you choose to add a drive, a new entry will be made
275 and a default drive mapping will appear. You can change where
276 this drive points to by changing what's in the
277 <guilabel>Path:</guilabel> box. If you're unsure of the
278 exact path you can choose <guibutton>Browse</guibutton> to search for it.
279 Removing a drive is as easy as selecting the drive and
280 clicking <guibutton>Remove</guibutton>.
282 <command>winecfg</command> has the ability to automatically detect the drives
283 available on your system. It's recommended you try this
284 before attempting to configure drives manually. Simply
285 click on the <guibutton>Autodetect</guibutton> button to
286 have Wine search for drives on your system.
288 You may be interested in configuring your drive settings
289 outside of <command>winecfg</command>, in which case you're in luck because it's
290 quite easy. All of the drive settings reside in a special
291 directory: <filename class="directory">~/.wine/dosdevices</filename>. Each
292 <quote>drive</quote> is simply a link to where it actually resides. Wine automatically
293 sets up two drives the first time you run Wine:
296 <prompt>$ </prompt><userinput>ls -la ~/.wine/dosdevices/</userinput>
297 <computeroutput>lrwxrwxrwx 1 <replaceable>wineuser</replaceable> <replaceable>wineuser</replaceable> 10 Jul 23 15:12 c: -> ../drive_c</computeroutput>
298 <computeroutput>lrwxrwxrwx 1 <replaceable>wineuser</replaceable> <replaceable>wineuser</replaceable> 1 Jul 23 15:12 z: -> /</computeroutput>
301 To add another drive, for example your CD-ROM, just create a new
302 link pointing to it:
305 <prompt>$ </prompt><userinput>ln -s /mnt/cdrom ~/.wine/dosdevices/d:</userinput>
308 Take note of the DOS-style naming convention used for links -
309 the format is a letter followed by a colon, such as <filename
310 class="devicefile">a:</filename>. So,
311 if the link to your <filename class="devicefile">c:</filename> drive points to
312 <filename class="directory">~/.wine/drive_c</filename>, you
313 can interpret references to <filename class="directory">c:\windows\system32</filename>
314 to mean <filename class="directory">~/.wine/drive_c/windows/system32</filename>.
318 <title>Audio Settings</title>
320 Wine can work with quite a few different audio subsystems.
321 You can see the selected driver that Wine figures out for you
322 under the <guilabel>Audio</guilabel> tab.
325 You can manually select which device will be used for
326 Output, Input, Voice output and Voice input. For example you can choose
327 the digital output of your sound device instead of the analog one.
331 <title>Desktop Integration</title>
333 Wine can load Windows themes if you have them available. While
334 this certainly isn't necessary in order to use Wine or applications,
335 it does allow you to customize the look and feel of a program. Wine
336 supports the newer MSStyles type of themes. Unlike the older <productname>Microsoft
337 Plus!</productname> style themes, the <literal>uxtheme</literal> engine supports special
338 <filename class="extension">.msstyles</filename> files
339 that can retheme all of the Windows controls. This is more or less the
340 same kind of theming that modern Linux desktops have supported for
341 years. If you'd like to try this out:
345 Download a Windows XP theme. Be sure it contains a
346 <filename class="extension">.msstyles</filename> file.
351 Use the <guilabel>Desktop Integration</guilabel> tab of
352 <command>winecfg</command> to install and select the new theme.
359 <sect1 id="using-regedit">
360 <title>Using the Registry and Regedit</title>
362 All of the settings you change in <command>winecfg</command>, with exception of
363 the drive settings, are ultimately stored in the registry.
364 In Windows, this is a central repository for the configuration
365 of applications and the operating system. Likewise, Wine
366 implements a registry and some settings not found in Winecfg
367 can be changed within it (there's actually more of a chance
368 you'll need to dip into the registry to change the settings of an application
369 than Wine itself).
372 Now, the fact that Wine itself uses the registry to store settings
373 has been controversial. Some people argue that it's too much like
374 Windows. To counter this there are several things to consider.
375 First, it's impossible to avoid implementing a registry simply
376 because applications expect to be able to store their settings there.
377 In order for Wine to store and access settings in a separate
378 configuration file would require a separate set of code to basically
379 do the same thing as the Win32 APIs Wine already implements.
382 <title>Registry Structure</title>
384 Okay... with that out of the way, let's dig into the registry a bit
385 to see how it's laid out. The Windows registry is an elaborate tree
386 structure, and not even most Windows programmers are fully aware of
387 how the registry is laid out, with its different <quote>hives</quote> and numerous
388 links between them; a full coverage is out of the scope of
389 this document. But here are the basic registry keys you might
390 need to know about for now:
397 This fundamental root key (in win9x it's stored in the
398 hidden file <filename>system.dat</filename>) contains
399 everything pertaining to the current Windows
400 installation. This is often abbreviated <literal>HKLM</literal>.
408 This fundamental root key (in win9x it's stored in the
409 hidden file <filename>user.dat</filename>) contains
410 configuration data for every user of the installation.
418 This is a link to <literal>HKEY_LOCAL_MACHINE\Software\Classes</literal>.
419 It contains data describing things like file
420 associations, OLE document handlers, and COM classes.
428 This is a link to
429 <literal>HKEY_USERS\<replaceable>your_username</replaceable></literal>, i.e., your
430 personal configuration.
437 <title>Registry Files</title>
439 Now, what you're probably wondering is how that translates
440 into Wine structure. The registry layout described above
441 actually lives in three different files within each user's
442 <filename class="directory">~/.wine</filename> directory:
449 This file contains <literal>HKEY_LOCAL_MACHINE</literal>.
457 This file contains <literal>HKEY_CURRENT_USER</literal>.
465 This file contains <literal>HKEY_USERS\.Default</literal> (i.e. the default
466 user settings).
472 These files are automatically created the first time you use
473 Wine. A set of global settings is stored in the
474 <filename>wine.inf</filename> file and is processed by
475 the <command>rundll32.exe</command> program. The first
476 time you run Wine the <filename>wine.inf</filename> file
477 gets processed to populate the initial registry. The
478 registry is also updated automatically
479 if <filename>wine.inf</filename> changes, for instance when
480 upgrading to a newer Wine version.
483 Note: Older Wine versions (before 1.0) required you to run
484 the <command>wineprefixcreate</command> command manually to
485 upgrade your settings. This is no longer necessary.
488 It is not advisable to edit these files to modify the registry
489 as they are managed by Wine internally. Use <command>regedit.exe</command>,
490 <command>reg.exe</command> or any program which uses the standard registry functions.
494 <title>Using Regedit</title>
496 An easy way to access and change the registry is with the
497 <command>regedit</command> tool. Similar to the Windows
498 program it replaces, <command>regedit</command> serves to provide a system level
499 view of the registry containing all of the keys. When you start it, you'll
500 immediately notice that the cryptic keys displayed in the text file
501 are organized in a hierarchical fashion.
504 To navigate through the registry, click on the keys on the
505 left to drill down deeper. To delete a key, click on it and
506 choose <guimenuitem>Delete</guimenuitem> from the <guimenu>Edit</guimenu> menu. To add a
507 key or value, locate where you want to put it and choose <guimenuitem>New</guimenuitem>
508 from the <guimenu>Edit</guimenu> menu. Likewise, you modify an existing key by
509 highlighting it in the right-hand window pane and choosing
510 <guimenuitem>Modify</guimenuitem> from the <guimenu>Edit</guimenu> menu. Another way to
511 perform these same actions is to right-click on the key or value.
514 Of particular interest to Wine users are the settings stored in
515 <literal>HKEY_CURRENT_USER\Software\Wine</literal>. Most of
516 the settings you change within <command>winecfg</command> are written to this area
517 of the registry.
521 <title>System Administration Tips</title>
523 With the above file structure, it is possible for a system
524 administrator to configure the system so that a system Wine
525 installation (and applications) can be shared by all the
526 users, and still let the users all have their own personalized
527 configuration. An administrator can, after having installed
528 Wine and any Windows application software he wants the users
529 to have access to, copy the resulting
530 <filename>system.reg</filename> and
531 over to the global registry files (which we assume will reside in
532 <filename class="directory">/usr/local/etc</filename> here), with:
535 cd ~root/.wine
536 cp system.reg /usr/local/etc/wine.systemreg
539 and perhaps even symlink these back to the administrator's
540 account, to make it easier to install apps system-wide later:
543 ln -sf /usr/local/etc/wine.systemreg system.reg
546 You might be tempted to do the same for <filename>user.reg</filename>
547 as well, however that file contains user specific settings.
548 Every user should have their own copy of that file along with
549 the permissions to modify it.
552 You'll want to pay attention to drive mappings. If
553 you're sharing the <filename>system.reg</filename> file you'll want to make sure
554 the registry settings are compatible with the drive mappings
555 in <filename class="directory">~/.wine/dosdevices</filename>
556 of each individual user. As a general rule of thumb, the closer
557 you keep your drive mappings to the default configuration, the easier
558 this will be to manage. You may or may not be able to share
559 some or all of the actual <filename class="devicefile">c:</filename> drive you
560 originally installed the application to. Some applications
561 require the ability to write specific settings to the drive,
562 especially those designed for Windows 95/98/ME.
565 Note that the <command>tools/wineinstall</command> script
566 used to do some of this if you installed Wine source as root, however
567 it no longer does.
570 A final word of caution: be careful with what you do with the
571 administrator account - if you do copy or link the administrator's
572 registry to the global registry, any user might be able to read the
573 administrator's preferences, which might not be good if
574 sensitive information (passwords, personal information, etc)
575 is stored there. Only use the administrator account to install
576 software, not for daily work; use an ordinary user account for
581 <title>Complete List of Registry Keys</title>
583 You'll find an up-to-date <ulink url="http://wiki.winehq.org/UsefulRegistryKeys"> list of
584 useful registry keys and values</ulink> in the wiki.
588 <sect1 id="misc-things-to-configure">
589 <title>Other Things to Configure</title>
591 This section is meant to cover the rest of the things you can configure.
592 It also serves as a collection of tips and tricks to get the most out
593 of using Wine.
596 <title>Serial and Parallel Ports</title>
598 Serial and parallel port configuration is very similar to drive
599 configuration - simply create a symbolic link in
600 <filename class="directory">~/.wine/dosdevices</filename> with the name of the
601 device. Windows serial ports follow a naming convention of the
602 word <literal>com</literal> followed by a number, such as
603 <filename class="devicefile">com1</filename>, <filename
604 class="devicefile">com2</filename>, etc. Similarly, parallel ports use
605 <literal>lpt</literal> followed by a
606 number, such as <filename class="devicefile">lpt1</filename>.
607 You should link these directly to the corresponding Unix
608 devices, such as <filename class="devicefile">/dev/ttyS0</filename> and
609 <filename class="devicefile">/dev/lp0</filename>. Make sure you have the needed
610 access rights to that device. For example, to configure
611 one serial port and one parallel port, run the following commands:
613 ln -s /dev/ttyS0 com1
614 ln -s /dev/lp0 lpt1
619 <title>Network Shares</title>
622 Windows shares can be mapped into the <filename class="directory">unc/</filename>
623 directory so anything trying to access
625 will look in
627 For example, if you used Samba to mount
628 <filename class="directory">\\<replaceable>myserver</replaceable>\<replaceable>some</replaceable></filename> on
631 then you can do
633 ln -s /mnt/smb/<replaceable>myserver</replaceable>/<replaceable>some</replaceable> unc/<replaceable>myserver</replaceable>/<replaceable>some</replaceable>
636 to make it available in Wine (don't forget to create the <filename
637 class="directory">unc</filename> directory if it doesn't already exist).
643 Font configuration, once a nasty problem, is now much simpler.
644 If you have a collection of TrueType fonts in Windows it's
645 simply a matter of copying the <filename class="extension">.ttf</filename> files
646 into <filename class="directory">c:\windows\fonts</filename>.
652 Wine can interact directly with the local CUPS printing system to
653 find the printers available on your system. Configuring
654 printers with Wine is as simple as making sure your CUPS
655 configuration works. Wine still needs the
656 <command>lpr</command> command (from CUPS), when printing a document.
659 If you do not use CUPS, the old BSD-Printing system is used:
663 All Printers from <filename>/etc/printcap</filename> are installed automatically in Wine.
668 Wine needs a PPD file for every Printer (<filename>generic.ppd</filename>
669 comes with Wine).
674 The <command>lpr</command> command is called when printing a document
683 In Windows, scanners use the TWAIN API to access the underlying
684 hardware. Wine builtin TWAIN DLL simply forwards those requests
685 to the Linux SANE libraries. So, to utilize your scanner under
686 Wine you'll first need to make sure you can access it using
687 SANE. After that you'll need to make sure you have
688 <command>xscanimage</command> available for use. Currently
689 it is shipped with the
690 <literal>sane-frontends</literal> package but it
691 may not be installed with your distribution. Scanner access
692 is currently known to have problems. If you find it works for
693 you, please consider updating this section of the user guide to
694 provide details on using SANE with Wine.
698 <title>ODBC Databases</title>
700 The ODBC system within Wine, as with the printing system, is designed
701 to hook across to the Unix system at a high level. Rather than
702 ensuring that all the Windows code works under Wine it uses a suitable
703 Unix ODBC provider, such as <literal>unixODBC</literal>. Thus if you configure Wine to
704 use the built-in <filename class="libraryfile">odbc32.dll</filename>,
705 that Wine DLL will interface to your
706 Unix ODBC package and let that do the work, whereas if you configure
707 Wine to use the native <filename class="libraryfile">odbc32.dll</filename>
708 it will try to use the native ODBC32 drivers etc.
711 <title>Configuring ODBC on Unix</title>
713 The first step in using a Unix ODBC system with Wine is, of course,
714 to get the Unix ODBC system working itself. This may involve
715 downloading code or binary packages etc. There are several Unix ODBC systems
716 available such as <literal>unixODBC</literal> or an ODBC-ODBC bridge that can be used
717 to access a Microsoft Access database. Typically such systems will
718 include a tool, such as <command>isql</command>, which will allow
719 you to access the data from the command line so that you can check
720 that the system is working.
723 The next step is to hook the Unix ODBC library to the Wine built-in
724 <filename class="libraryfile">odbc32</filename> DLL. The built-in <filename
725 class="libraryfile">odbc32</filename> (currently)
726 looks to the environment variable
727 <envar>LIB_ODBC_DRIVER_MANAGER</envar> for the name of the ODBC
728 library. For example:
734 If that environment variable is not set then it looks for a
735 library called <filename class="libraryfile">libodbc.so</filename> and so
736 you can add a symbolic link to
737 equate that to your own library. For example as root you could
738 run the commands:
741 <prompt># </prompt><userinput>ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so</userinput>
742 <prompt># </prompt><userinput>/sbin/ldconfig</userinput>
745 The last step in configuring this is to ensure that Wine is set up
746 to run the built-in version of <filename class="libraryfile">odbc32.dll</filename>,
747 by modifying the DLL
748 configuration. This built-in DLL merely acts as a stub between the
749 calling code and the Unix ODBC library.
752 If you have any problems then you can use
753 <userinput><envar>WINEDEBUG</envar>=+odbc32</userinput> command
754 before running Wine to trace what is happening. One word of
755 warning: some programs actually cheat a little and bypass the ODBC
756 library. For example the Crystal Reports engine goes to the registry
757 to check on the DSN. The fix for this is documented at <literal>unixODBC</literal>
758 site where there is a section on using <literal>unixODBC</literal> with Wine.
762 <title>Using Windows ODBC drivers</title>
764 Native ODBC drivers have been reported to work for many types of
765 databases including MSSQL and Oracle. In fact, some like MSSQL can
766 only be accessed on Linux through a Winelib app. Rather than
767 just copying DLL files, most ODBC drivers require a Windows-based
768 installer to run to properly configure things such as registry keys.
771 In order to set up MSSQL support you will first need to download
772 and run the <command>mdac_typ.exe</command> installer from <uri
773 type="homepage">www.microsoft.com</uri>. In order to
774 configure your ODBC connections you must then run <command>CLICONFG.EXE</command>
775 and <command>ODBCAD32.EXE</command> under Wine. You can find them in the
776 <filename class="directory">windows\system</filename>
777 directory after mdac_typ runs. Compare the output of these programs
778 with the output on a native Windows machine. Some things, such
779 as protocols, may be missing because they rely on being installed
780 along with the operating system. If so, you may be able to copy
781 missing functionality from an existing Windows installation as
782 well as any registry values required. A native Windows installation
783 configured to be used by Wine should work the same way it did
784 when run natively.
787 Types successfully tested under Wine:
790 <tgroup cols="2">
793 <entry>DB Type</entry>
799 <entry>MS SQL</entry>
806 Please report any other successes to the
807 <ulink url="mailto:email@example.com">wine-devel</ulink>
808 mailing list.