Wine User Guide
Wine User Guide
Wine User Guide
Table of Contents
1. Introduction .............................................................................................................................................................. 1 Overview / About.................................................................................................................................................. 1 What is Wine?....................................................................................................................................................... 1 Versions of Wine................................................................................................................................................... 3 Alternatives to Wine you might want to consider................................................................................................. 4 2. Getting Wine ............................................................................................................................................................. 5 Wine Installation Methods.................................................................................................................................... 5 Installing Wine from a package ............................................................................................................................ 5 Installing Wine from source ................................................................................................................................. 6 3. Conguring Wine ..................................................................................................................................................... 8 Using Winecfg ...................................................................................................................................................... 8 Using the Registry and Regedit .......................................................................................................................... 11 Other Things to Congure .................................................................................................................................. 13 4. Running Wine ......................................................................................................................................................... 16 Basic usage: applications and control panel applets........................................................................................... 16 How to run Wine................................................................................................................................................. 16 Explorer-like graphical Wine environments ....................................................................................................... 17 Wine Command Line Options ............................................................................................................................ 17 Environment variables ........................................................................................................................................ 17 wineserver Command Line Options ................................................................................................................... 19 Setting Windows/DOS environment variables ................................................................................................... 20 Text mode programs (CUI: Console User Interface).......................................................................................... 21 5. Troubleshooting / Reporting bugs......................................................................................................................... 25 What to do if some program still doesnt work? ................................................................................................ 25 How To Report A Bug ........................................................................................................................................ 26 Glossary....................................................................................................................................................................... 29
iii
Chapter 1. Introduction
Overview / About
Purpose of this document and intended audience
This document, called the Wine User Guide, is both an easy installation guide and an extensive reference guide. This guide is for both the new Wine user and the experienced Wine user, offering full step-by-step installation and conguration instructions, as well as featuring extensive reference material by documenting all conguration features and support areas.
Quick start
The process of installing and running wine can be summarised as follows:
Get a distribution as indicated in Getting Wine and see the Wine Downloads (http://www.winehq.org/site/download) page. For the casual or new user the simplest is to get an rpm distribution. Congure wine using the winecfg command. For most people wine should now be usable. To test your installation run wines Windows 3.1 like le manager using the wine winefile command. Run wine using the wine filespec/appname.exe command. The rst command you will run will be to install a package. Typically something like wine
/media/cdrom/setup.exe or the equivalent.
Chapter 1. Introduction
What is Wine?
Windows and Linux
Different software programs are designed for different operating systems, and most wont work on systems that they werent designed for. Windows programs, for example, wont run in Linux because they contain instructions that the system cant understand until theyre translated by the Windows environment. Linux programs, likewise, wont run under the Windows operating system because Windows is unable to interpret all of their instructions. This situation presents a fundamental problem for anyone who wants to run software for both Windows and Linux. A common solution to this problem is to install both operating systems on the same computer, known as "dual booting." When a Windows program is needed, the user boots the machine into Windows to run it; when a Linux program is then needed, the user then reboots the machine into Linux. This option presents great difculty: not only must the user endure the frustration of frequent rebooting, but programs for both platforms cant be run simultaneously. Having Windows on a system also creates an added burden: the software is expensive, requires a separate disk partition, and is unable to read most lesystem formats, making the sharing of data between operating systems difcult.
Wine features
Throughout the course of its development, Wine has continually grown in the features it carries and the programs it can run. A partial list of these features follows: Support for running Win32 (Win 95/98, NT/2000/XP), Win16 (Win 3.1) and DOS programs Optional use of external vendor DLL les (such as those included with Windows) X11-based graphics display, allowing remote display to any X terminal, as well as a text mode console Desktop-in-a-box or mixable windows DirectX support for games Good support for various sound drivers including OSS and ALSA Support for alternative input devices Printing: PostScript interface driver (psdrv) to standard Unix PostScript print services Modem, serial device support
Chapter 1. Introduction
Winsock TCP/IP networking support ASPI interface (SCSI) support for scanners, CD writers, and other devices Advanced unicode and foreign language support Full-featured Wine debugger and congurable trace logging messages for easier troubleshooting
Versions of Wine
Wine from Wine HQ
Wine is an open source project, and there are accordingly many different versions of Wine for you to choose from. The standard version of Wine comes in intermittent releases (roughly twice a month), and can be downloaded over the internet in both prepackaged binary form and ready to compile source code form. Alternatively, you can install a development version of Wine by using the latest available source code from the Git repository. See the next chapter, Getting Wine, for further details.
CodeWeavers CrossOver Ofce CrossOver Ofce allows you to install your favorite Windows (http://www.codeweavers.com/products/ofce) productivity applications in Linux, without needing a Microsoft Operating System license. CrossOver includes an easy to use, single click interface, which makes installing a Windows application simple and fast. CodeWeavers CrossOver Ofce CrossOver Ofce Server Edition Server Edition allows you to run your favorite (http://www.codeweavers.com/products/cxofceserver) Windows productivity applications in a distributed thin-client environment under Linux, without needing Microsoft Operating System licenses for each client machine. CrossOver Ofce Server Edition allows you to satisfy the needs of literally hundreds of concurrent users, all from a single server.
Chapter 1. Introduction
Native Applications
Instead of running a particular Windows application with Wine, one frequently viable alternative is to simply run a different application. Many Windows applications, particularly more commonly used ones such as media players, instant messengers, and lesharing programs have very good open source equivalents. Furthermore, a sizable number of Windows programs have been ported to Linux directly, eliminating the need for Wine (or Windows) entirely.
Virtual Machines
Rather than installing an entirely new operating system on your machine, you can instead run a virtual machine at the software level and install a different operating system on it. Thus, you could run a Linux system and at the same time run Windows along with your application in a virtual machine simultaneously on the same hardware. Virtual machines allow you to install and run not only different versions of Windows on the same hardware, but also other operating systems, including ReactOS. There are several different virtual machine offerings out there, and some are also able to emulate x86 hardware on different platforms. The open source Bochs (http://bochs.sourceforge.net/) and QEMU (http://www.qemu.org/) can run both Windows and ReactOS virtually. Other, commercial virtual machine offerings include VMware (http://www.vmware.com/) and Microsofts VirtualPC (http://www.microsoft.com/windows/virtualpc/). There are signicant drawbacks to using virtual machines, however. Unlike Wine, such programs are emulators, so there is an inevitable speed decrease which can be quite substantial. Furthermore, running an application inside a virtual machine prevents fully integrating the application within the current environment. You wont, for example, be able to have windows system tray icons or program shortcuts sitting alongside your desktop Linux ones, since instead the Windows applications must reside completely within the virtual machine.
Different Distributions
Wine works on a huge amount of different Linux distributions, as well other Unix-like systems such as Solaris and FreeBSD, each with their own specic way of installing and managing packages. Fortunately, however, the same general ideas apply to all of them, and installing Wine should be no more difcult than installing any other software, no matter what distribution you use. Uninstalling Wine packages is simple as well, and in modern Linux distributions is usually done through the same easy interface as package installation. We wont cover the specics of installing or uninstalling Wine packages among the various systems methods of packaging and package management in this guide, however, up to date installation notes for particular distributions can be found at the WineHQ website in the HowTo (http://www.winehq.org/site/howto). If you need further help guring out how to simply install a Wine package, we suggest consulting your distributions documentation, support forums, or IRC channels.
Compiling Wine
Once youve installed the build dependencies you need, youre ready to compile the package. In the terminal window, after having navigated to the Wine source tree, run the following commands:
$ ./configure
The last command requires root privileges. Although you should never run Wine as root, you will need to install it this way.
This command will require root privileges, and should remove all of the Wine binary les from your system. It will not, however, remove your Wine conguration and applications located in your users home directory, so you are free to install another version of Wine or delete that conguration by hand.
Using Winecfg
In the past, Wine used a special conguration le that could be found in ~/.wine/config. If you are still using a version of Wine that references this le (older than June, 2005) you should upgrade before doing anything else. All settings are now stored directly in the registry and accessed by Wine when it starts. Winecfg should have been installed on your computer along with the rest of the Wine programs. If you cant gure out how to start it, try running the command: $ /usr/local/bin/winecfg or possibly just: $ winecfg When the program starts youll notice there are tabs along the top of the window for:
Changing settings in the Applications and Libraries tab will have the most impact on getting an application to run. The other settings focus on getting Wine itself to behave the way you want it to. Note: The Applications, Libraries, and Graphics tabs are linked together! If you have Default Settings selected under Applications, all of the changes made within the Libraries and Graphics tabs will be changed for all applications. If youve congured a specc application under the Applications tab and have it selected, then any changes made in Libraries or Graphics will affect only that application. This allows for custom settings for specic applications.
Application Settings
Wine has the ability to mimic the behavior of different versions of Windows. In general, the biggest difference is whether Wine behaves as a Win9x version or an NT version. Some applications require a specic behavior in order to function and changing this setting may cause a buggy app to work. Recently Wines default Windows version has changed to Windows 2000. Its known that many applications will perform better if you choose Windows 98. Within the tab youll notice there is a Default Settings entry. If you select that youll see the current default Windows Version for all applications. A troublesome application is best congured separately from the Default Settings. To do that: 1. Click on the Add application button. 2. Browse until you locate the .exe
3. After its been added you can choose the specic Windows version Wine will emulate for that application.
Libraries Settings
Likewise, some applications require specic libraries in order to run. Wine reproduces the Windows system libraries (so-called native DLLs) with completely custom versions designed to function exactly the same way but without requiring licenses from Microsoft. Wine has many known deciencies in its built-in versions, but in many instances the functionality is sufcient. Using only builtin DLLs ensures that your system is Microsoft-free. However, Wine has the ability to load native Windows DLLs.
DLL Overrides
Its not always possible to run an application on builtin DLLs. Sometimes native DLLs simply work better. After youve located a native DLL on a Windows system, youll need to put it in suitable place for Wine to nd it and then congure it to be used. Generally the place you need to put it is in the directory youve congured to be c:\windows\system32 (more on that in the drives section). There are four DLLs you should never try to use the native versions of: kernel32.dll, gdi32.dll, user32.dll, and ntdll.dll. These libraries require low-level Windows kernel access that simply doesnt exist within Wine. With that in mind, once youve copied the DLL you just need to tell Wine to try to use it. You can congure Wine to choose between native and builtin DLLs at two different levels. If you have Default Settings selected in the Applications tab, the changes you make will affect all applications. Or, you can override the global settings on a per-application level by adding and selecting an application in the Applications tab. To add an override for FOO.DLL, enter "FOO" into the box labeled New override for library: and click on the Add button. To change how the DLL behaves, select it within the Existing overrides: box and choose Edit. By default the new load order will be native Windows libraries before Wines own builtin ones (Native then Builtin). You can also choose native only, builtin only, or disable it altogether.
Missing DLLs
In case Wine complains about a missing DLL, you should check whether this le is a publicly available DLL or a custom DLL belonging to your program (by searching for its name on the internet). After youve located the DLL,
you need to make sure Wine is able to use it. DLLs usually get loaded in the following order: 1. The directory the program was started from. 2. The current directory. 3. The Windows system directory. 4. The Windows directory. 5. The PATH variable directories. In short: either put the required DLL into your program directory (might be ugly), or put it into the Windows system directory. Also, if possible you probably shouldnt use NT-based native DLLs, since Wines NT API support is somewhat weaker than its Win9x API support (possibly leading to even worse compatibility with NT DLLs than with a no-windows setup!).
Graphics Settings
There are basically ve different graphics settings you can congure. For most people the defaults are ne. The rst few settings primarily affect games and are somewhat self-explanatory. You can prevent the mouse from leaving the window of a DirectX program (i.e. a game.) and the default is to have that box checked. Theres lots of reasons you might want to do that, not the least of which includes its easier to play the game if the cursor is conned to a smaller area. The other reason to turn this option on is for more precise control of the mouse - Wine warps the location of the mouse to mimic the way Windows works. Similarly, "desktop double buffering" allows for smoother updates to the screen, which games can benet from, and the default is to leave it turned on. The tradeoff is increased memory use. You may nd it helpful to Emulate a virtual desktop. In this case, all programs will run in a separate window. You may nd this useful as a way to test buggy games that change (possibly unsuccessfully) the screen resolution. Conning them to a window can allow for more control over them at the possible expense of decreased usability. Sizes you might want to try are 640x480 (the default) or 800x600. Finally, you can congure some Direct3D settings. For the most part these settings are detected automatically, but you can force them to behave in a specic manner. Some games attempt to probe the underlying system to see if it supports specic features. By turning these off Wine wont report the ability to render games in a certain way. It may lead to the game running faster at the expense of the quality of the graphics or the game may not run at all.
Drive Settings
Windows requires a fairly rigid drive conguration that Wine imitates. Most people are familiar with the standard notation of the "A:" drive representing the oppy disk, the "C:" drive representing the primary system disk, etc. Wine uses the same concept and maps those drives to the underlying native lesystem. Wines drive conguration is relatively simple. In Winecfg under the Drives tab youll see buttons to add and remove available drives. When you choose to add a drive, a new entry will be made and a default drive mapping will appear. You can change where this drives points to by changing whats in the Path: box. If youre unsure of the exact path you can choose "Browse" to search for it. Removing a drive is as easy as selecting the drive and clicking "Remove". Winecfg has the ability to automatically detect the drives available on your system. Its recommended you try this before attempting to congure drives manually. Simply click on the Autodetect button to have Wine search for drives on your system. You may be interested in conguring your drive settings outside of Winecfg, in which case youre in luck because its quite easy. All of the drive settings reside in a special directory, ~/.wine/dosdevices. Each "drive" is simply a link to where it actually resides. Wine automatically sets up two drives the rst time you run Wine:
10
To add another drive, for example your CD-ROM, just create a new link pointing to it: $ ln -s /mnt/cdrom ~/.wine/dosdevices/d: Take note of the DOS-style naming convention used for links - the format is a letter followed by a colon, such as "a:". So, if the link to your c: drive points to ~/.wine/drive_c, you can interpret references to c:\windows\system32 to mean ~/.wine/drive_c/windows/system32.
Audio Settings
Wine can work with quite a few different audio subsystems which you can choose under the "Audio" tab. winecfg gures out all available drivers for you, but you can manually select which driver will be used. Older Linux distributions using the 2.4 kernel or earlier typically use the "OSS" driver. Usually 2.6 kernels have switched to "ALSA". The "aRts" driver was recently deactivated due to the general lack of maintenance of the "aRts" subsystem. If youre using GNOME you can probably use EsounD. The OSS and ALSA audio drivers get the most testing, so its recommended you stick with them if possible. If you need to use "Jack", "NAS" or "CoreAudio" you probably already know why. DirectSound settings are primarily used by games. You can choose what level of hardware acceleration youd like, but for most people "Full" is ne.
Desktop Integration
Wine can load Windows themes if you have them available. While this certainly isnt necessary in order to use Wine or applications, it does allow you to customize the look and feel of a program. Wine supports the newer MSStyles typ of themese. Unlike the older Microsoft Plus! style themes, the uxtheme engine supports special .msstyles les that can retheme all of the Windows controls. This is more or less the same kind of theming that modern Linux desktops have supported for years. If youd like to try this out:
1. Download a Windows XP theme. Be sure it contains a .msstyles le. 2. Create a set of new directories in your fake Windows drive: $ mkdir -p
~/.wine/drive_c/windows/Resources/themes/name-of-your-theme
3. Move the .msstyles to that new name-of-your-theme directory. 4. Use the Desktop Integration tab of winecfg to select the new theme.
11
can be changed using your favorite text editor. While most sane system administrators (and Wine developers) curse madly at the twisted nature of the Windows registry, it is still necessary for Wine to support it somehow.
Registry Structure
Okay.. with that out of the way, lets dig into the registry a bit to see how its laid out. The Windows registry is an elaborate tree structure, and not even most Windows programmers are fully aware of how the registry is laid out, with its different "hives" and numerous links between them; a full coverage is out of the scope of this document. But here are the basic registry keys you might need to know about for now: HKEY_LOCAL_MACHINE This fundamental root key (in win9x its stored in the hidden le system.dat) contains everything pertaining to the current Windows installation. This is often abbreviated HKLM. HKEY_USERS This fundamental root key (in win9x its stored in the hidden le user.dat) contains conguration data for every user of the installation. HKEY_CLASSES_ROOT This is a link to HKEY_LOCAL_MACHINE\Software\Classes. It contains data describing things like le associations, OLE document handlers, and COM classes. HKEY_CURRENT_USER This is a link to HKEY_USERS\your_username, i.e., your personal conguration.
Registry Files
Now, what youre probably wondering is how that translates into Wines structure. The registry layout described above actually lives in three different les within each users ~/.wine directory:
system.reg
This le contains HKEY_USERS\.Default (i.e. the default user settings). These les are automatically created the rst time you use Wine. A set of global settings is stored in the wine.inf le and is processed by the rundll32.exe program. The rst time you run Wine the wine.inf le gets processed to populate the initial registry. The registry is also updated automatically if wine.inf changes, for instance when upgrading to a newer Wine version. Note: Older Wine versions (before 1.0) required you to run the wineprexcreate command manually to upgrade your settings. This is no longer necessary. Like we mentioned, you can edit those .reg les using whatever text editor you want. Just make sure Wine isnt running when you do it, otherwise all of the changes will be lost.
Using Regedit
An easier way to access and change the registry is with the tool regedit. Similar to the Windows program it replaces, regedit serves to provide a system level view of the registry containing all of the keys. Simply run regedit
12
and it should pop up. Youll immediately notice that the cryptic keys displayed in the text le are organized in a hierarchical fashion. To navigate through the registry, click on the keys on the left to drill down deeper. To delete a key, click on it and choose "Delete" from the Edit menu. To add a key or value, locate where you want to put it and choose "New" from the Edit menu. Likewise, you modify an existing key by highlighting it in the right-hand window pane and choosing "Modify" from the Edit menu. Another way to perform these same actions is to right-click on the key or value. Of particular interest to Wine users are the settings stored in HKEY_CURRENT_USER\Software\Wine. Most of the settings you change within winecfg are written to this area of the registry.
and perhaps even symlink these back to the administrators account, to make it easier to install apps system-wide later:
ln -sf /usr/local/etc/wine.systemreg system.reg
You might be tempted to do the same for user.reg as well, however that le contains user specic settings. Every user should have their own copy of that le along with the permissions to modify it. Youll want to pay attention to drive mappings. If youre sharing the system.reg le youll want to make sure the registry settings are compatible with the drive mappings in ~/.wine/dosdevices of each individual user. As a general rule of thumb, the closer you keep your drive mappings to the default conguration, the easier this will be to manage. You may or may not be able to share some or all of the actual "c:" drive you originally installed the application to. Some applications require the ability to write specic settings to the drive, especially those designed for Windows 95/98/ME. Note that the tools/wineinstall script used to do some of this if you installed Wine source as root, however it no longer does. A nal word of caution: be careful with what you do with the administrator account - if you do copy or link the administrators registry to the global registry, any user might be able to read the administrators preferences, which might not be good if sensitive information (passwords, personal information, etc) is stored there. Only use the administrator account to install software, not for daily work; use an ordinary user account for that.
13
Network Shares
Windows shares can are mapped into the unc/ directory so anything trying to access \\myserver\some\file will look in ~/.wine/dosdevices/unc/myserver/some/file/. For example, if you used Samba to mount \\myserver\some on /mnt/smb/myserver/some then you can do
ln -s /mnt/smb/myserver/some unc/myserver/some
to make it available in wine (dont forget to create the unc directory if it doesnt alrady exist).
Fonts
Font conguration, once a nasty problem, is now much simpler. If you have a collection of TrueType fonts in Windows its simply a matter of copying the .ttf les into c:\windows\fonts.
Printers
Wine can interact directly with the local CUPS printing system to nd the printers available on your system. Conguring printers with Wine is as simple as making sure your CUPS conguration works. Wine still needs the command lpr(from CUPS), when printing a Document. If you do not use CUPS, the old BSD-Printing system is used:
All Printers from /etc/printcap are installed automatically in Wine. Wine needs a PPD-File for every Printer (generic.ppd comes with Wine) The command lpr is called when printing a Document
Scanners
In Windows, scanners use the TWAIN API to access the underlying hardware. Wines builtin TWAIN DLL simply forwards those requests to the Linux SANE libraries. So, to utilize your scanner under Wine youll rst need to make sure you can access it using SANE. After that youll need to make sure you have xscanimage available for use. Currently xscanimage is shipped with the sane-frontends package but it may not be installed with your distribution. Scanner access is currently known to have problems. If you nd it works for you, please consider updating this section of the user guide to provide details on using SANE with Wine.
14
ODBC Databases
The ODBC system within Wine, as with the printing system, is designed to hook across to the Unix system at a high level. Rather than ensuring that all the windows code works under wine it uses a suitable Unix ODBC provider, such as UnixODBC. Thus if you congure Wine to use the built-in odbc32.dll, that Wine DLL will interface to your Unix ODBC package and let that do the work, whereas if you congure Wine to use the native odbc32.dll it will try to use the native ODBC32 drivers etc.
If that environment variable is not set then it looks for a library called libodbc.so and so you can add a symbolic link to equate that to your own library. For example as root you could run the commands:
$ ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so $ /sbin/ldconfig
The last step in conguring this is to ensure that Wine is set up to run the built-in version of odbc32.dll, by modifying the DLL conguration. This built-in DLL merely acts as a stub between the calling code and the Unix ODBC library. If you have any problems then you can use WINEDEBUG=+odbc32 command before running wine to trace what is happening. One word of warning. Some programs actually cheat a little and bypass the ODBC library. For example the Crystal Reports engine goes to the registry to check on the DSN. The x for this is documented at unixODBCs site where there is a section on using unixODBC with Wine.
Please report any other successes to the wine-devel (mailto:[email protected]) mailing list.
15
Some programs install associated control panel applets, examples of this would be Internet Explorer and QuickTime. You can access the Wine control panel by running in a terminal:
$ wine control
which will open a window with the installed control panel applets in it, as in Windows. If the application doesnt install menu or desktop items, youll need to run the app from the command line. Remembering where you installed to, something like:
$ wine "c:\program files\appname\appname.exe"
will probably do the trick. The path isnt case sensitive, but remember to include the double quotes. Some programs dont always use obvious naming for their directories and EXE les, so you might have to look inside the program les directory to see what was put where.
The rst argument should be the name of the le you want wine to execute. If the executable is in the Path environment variable, you can simply give the executable le name. However, if the executable is not in Path, you must give the full path to the executable (in Windows format, not UNIX format!). For example, given a Path of the following:
Path="c:\windows;c:\windows\system;e:\;e:\test;f:\"
16
However, you would have to run the le c:\myapps\foo.exe with this command:
$ wine c:\\myapps\\foo.exe
(note the backslash-escaped "\" !) For details on running text mode (CUI) executables, read the section below.
--version
Shows the Wine version string. Useful to verify your installation.
Environment variables
WINEDEBUG=[channels]
Wine isnt perfect, and many Windows applications still dont run without bugs under Wine (but then, a lot of programs dont run without bugs under native Windows either!). To make it easier for people to track down the causes behind each bug, Wine provides a number of debug channels that you can tap into. Each debug channel, when activated, will trigger logging messages to be displayed to the console where you invoked wine. From there you can redirect the messages to a le and examine it at your leisure. But be forewarned! Some debug channels can generate incredible volumes of log messages. Among the most prolic offenders are relay which spits out a log message every time a win32 function is called, win which tracks windows message passing, and of course all which is an alias for every single debug channel that exists. For a complex application, your debug logs can easily top 1 MB and higher. A relay trace can often generate more than 10 MB of log messages, depending on how long you run the application. (Youll want to check out RelayExclude registry key to modify what the relay trace reports). Logging does slow down Wine quite a bit, so dont use WINEDEBUG unless you really do want log les. Within each debug channel, you can further specify a message class, to lter out the different severities of errors. The four message classes are: trace, fixme, warn, err . To turn on a debug channel, use the form class+channel. To turn it off, use class-channel. To list more than one channel in the same WINEDEBUG option, separate them with commas. For example, to request warn class messages in the heap debug channel, you could invoke wine like this:
17
If you leave off the message class, wine will display messages from all four classes for that channel:
$ WINEDEBUG=heap wine program_name
If you wanted to see log messages for everything except the relay channel, you might do something like this:
$ WINEDEBUG=+all,-relay wine program_name
Here is a list of the debug channels and classes in Wine. More channels will be added to (or subtracted from) later versions. Table 4-1. Debug Channels accel atom bitmap cfgmgr32 comboex console d3d ddeml debugstr dma dmime dmusic dpnhpast enhmetale le gdi heap imagehlp int31 joystick loaddll mciavi menu mmaux monthcal msg msrle32 netapi32 odbc pager process psdrv adpcm avicap cabinet class comm crtdll d3d_shader ddraw devenum dmband dmloader dosfs driver environ xup global hook imagelist io key local mcicda menubuilder mmio mpeg3 mshtml msvcrt netbios ole palette prole qcap advapi avile capi clipboard commctrl crypt d3d_surface ddraw_fps dialog dmcompos dmscript dosmem dsound event font glu hotkey imm ipaddress keyboard mapi mcimidi message mmsys mpr msi msvideo nls oledlg pidl progress quartz animate bidi caret clipping commdlg curses datetime ddraw_geom dinput dmle dmstyle dplay dsound3d eventlog fps graphics icmp int iphlpapi listbox mci mciwave metale mmtime msacm msimg32 mswsock nonclient olerelay powermgnt propsheet ras aspi bitblt cdrom combo computername cursor dc ddraw_tex dll dmledat dmsynth dplayx edit exec g711 header icon int21 jack listview mcianim mdi midi module msdmo msisys nativefont ntdll opengl print psapi rebar
18
reg rundll32 server snmpapi storage tab thread toolhelp twain uxtheme wc_font wineconsole wininet wintab32 xrandr
region sblaster setupapi snoop stress tape thunk tooltips typelib ver win wine_d3d winmm wnet xrender
relay scroll shdocvw sound string tapi tid trackbar uninstaller virtual win32 winevdm winsock x11drv xvidmode
resource seh shell static syscolor task timer treeview updown vxd wineboot wing winspool x11settings
richedit selector shlctrl statusbar system text toolbar ttydrv urlmon wave winecfg winhelp wintab xdnd
For more details about debug channels, check out the The Wine Developers Guide (http://www.winehq.org/site/docs/winedev-guide/).
WINEDLLOVERRIDES=[DLL Overrides]
Its not always possible to run an application on builtin DLLs. Sometimes native DLLs simply work better. Altough these DLL overrides can be set using winecfg you might want to use the WINEDLLOVERRIDES environment variable to set them. For example, if you wanted wine to use native ole32.dll, oleaut32.dll and rpcrt4 you could run wine like this:
$ WINEDLLOVERRIDES="ole32,oleaut32,rpcrt4=n" wine program_name
For more information about DLL overrides, please refer to the DLL overrides section of this guide.
As an example:
$ AUDIODEV=/dev/dsp4 MIXERDEV=/dev/mixer1 MIDIDEV=/dev/midi3 wine program_name
19
-d<n>
Sets the debug level for debug output in the terminal that wineserver got started in at level <n>. In other words: everything greater than 0 will enable wineserver specic debugging output.
-h
Display wineserver command line options help message.
-k[n]
Kill the current wineserver, optionally with signal n.
-p[n]
This parameter makes wineserver persistent, optionally for n seconds. It will prevent wineserver from shutting down immediately. Usually, wineserver quits almost immediately after the last wine process using this wineserver terminated. However, since wineserver loads a lot of things on startup (such as the whole Windows registry data), its startup might be so slow that its very useful to keep it from exiting after the end of all Wine sessions, by making it persistent.
-w
This parameter makes a newly started wineserver wait until the currently active wineserver instance terminates.
This will make sure your Windows program can access the MYENVIRONMENTVAR environment variable once you start your program using Wine. If you want to have MYENVIRONMENTVAR set permanently, then you can place the setting into /etc/prole, or also ~/.bashrc in the case of bash. Note however that there are some exceptions to the rule: If you want to change the PATH, SYSTEM or TEMP variables, the of course you cant modify it that way, since this will alter the Unix environment settings. Instead, you should set them into the registry. To set them you should launch wine regedit and then go to the
HKEY_CURRENT_USER/Environment
key. Now you can create or modify the values of the variables you need
20
"System" = "c:\\windows\\system"
This sets up where the windows system les are. The Windows system directory should reside below the directory used for the Windows setting. Thus when using /usr/local/wine_c_windows as Windows path, the system directory would be /usr/local/wine_c/windows/system. It must be set with no trailing slash, and you must be sure that you have write access to it.
"Temp" = "c:\\temp"
This should be the directory you want your temp les stored in, /usr/local/wine_c/temp in our previous example. Again, no trailing slash, and write access!!
"Path" = "c:\\windows;c:\\windows\\system;c:\\blanco"
Behaves like the PATH setting on UNIX boxes. When wine is run like wine sol.exe, if sol.exe resides in a directory specied in the Path setting, wine will run it (Of course, if sol.exe resides in the current directory, wine will run that one). Make sure it always has your windows directory and system directory (For this setup, it must have "c:\\windows;c:\\windows\\system").
bare streams wineconsole with user backend wineconsole with curses backend
The names here are a bit obscure. "bare streams" means that no extra support of wine is provide to map between the unix console access and Windows console access. The two other ways require the use of a specic Wine program (wineconsole) which provide extended facilities. The following table describes what you can do (and cannot do) with those three ways. Table 4-2. Basic differences in consoles Function How to run (assuming executable is called foo.exe) Good support for line oriented CUI applications (which print information line after line) Bare streams
$ wine foo.exe
Wineconsole & curses backend You can also use --backend=curses as an option
Yes
Yes
Yes
21
Function Good support for full screen CUI applications (including but not limited to color support, mouse support...) Can be run even if X11 is not running Implementation
Bare streams No
Yes Maps the standard Windows streams to the standard Unix streams (stdin/stdout/stderr)
No Wineconsole will create a new Window (hence requiring the USER32 DLL is available) where all information will be displayed
Yes Wineconsole will use existing unix console (from which the program is run) and with the help of the (n)curses library take control of all the terminal surface for interacting with the user Will produce strange behavior if two (or more) Windows consoles are used on the same Un*x terminal.
Known limitations
Default: this will edit the settings shared by all applications which havent been congured yet. So, when an application is rst run (on your machine, under your account) in wineconsole, wineconsole will inherit this default settings for the application. Afterwards, the application will have its own settings, that youll be able to modify at your will. Properties: this will edit the applications settings. When youre done, with the edition, youll be prompted whether you want to: 1. Keep these modied settings only for this session (next time you run the application, you will not see the modication youve just made). 2. Use the settings for this session and save them as well, so that next you run your application, youll use these new settings again.
Heres the list of the items you can congure, and their meanings:
22
Table 4-3. Wineconsole conguration options Conguration option Cursors size Meaning Denes the size of the cursor. Three options are available: small (33% of character height), medium (66%) and large (100%) Its been said earlier that wineconsole conguration popup was triggered using a right click in the consoles window. However, this can be an issue when the application you run inside wineconsole expects the right click events to be sent to it. By ticking control or shift you select additional modiers on the right click for opening the popup. For example, ticking shift will send events to the application when you right click the window without shift being hold down, and open the window when you right-click while shift being hold down. This tick box lets you decide whether left-click mouse events shall be interpreted as events to be sent to the underlying application (tick off) or as a selection of rectangular part of the screen to be later on copied onto the clipboard (tick on). This lets you pick up how many commands you want the console to recall. You can also drive whether you want, when entering several times the same command potentially intertwined with others - whether you want to store all of them (tick off) or only the last one (tick on). The Police property sheet allows you to pick the default font for the console (font le, size, background and foreground color). The console as you see it is made of two different parts. On one hand theres the screenbuffer which contains all the information your application puts on the screen, and the window which displays a given area of this screen buffer. Note that the window is always smaller or of the same size than the screen buffer. Having a strictly smaller window size will put on scrollbars on the window so that you can see the whole screenbuffers content. If its ticked, then the wineconsole will exit when the application within terminates. Otherwise, itll remain opened until the user manually closes it: this allows seeing the latest information of a program after it has terminated.
Popup menu
Quick edit
History
Police
Close on exit
23
Meaning When the user enter commands, he or she can choose between several edition modes: Emacs: the same keybindings as under emacs are available. For example, Ctrl-A will bring the cursor to the beginning of the edition line. See your emacs manual for the details of the commands. Win32: these are the standard Windows console key-bindings (mainly using arrows).
24
25
Recongure Wine
Sometimes wine installation process changes and new versions of Wine account on these changes. This is especially true if your setup was created long time ago. Rename your existing ~/.wine directory for backup purposes. Use the setup process thats recommended for your Wine distribution to create new conguration. Use information in old ~/.wine directory as a reference. Later you can remove the new ~/.wine directory and rename your old one back.
Debug it!
Finding the source of your problem is the next step to take. There is a wide spectrum of possible problems ranging from simple congurations issues to completely unimplemented functionality in Wine. The next section will describe how to le a bug report and how to begin debugging a crash. For more information on using Wines debugging facilities be sure to read the Wine Developers Guide.
26
Which version of Wine youre using (run wine --version) The name of the Operating system youre using, what distribution (if any), and what version. (i.e., Linux Red Hat 7.2) Which compiler and version, (run gcc -v). If you didnt compile wine then the name of the package and where you got it from. Windows version, if used with Wine. Mention if you dont use Windows. The name of the program youre trying to run, its version number, and a URL for where the program can be obtained (if available). The exact command line you used to start wine. (i.e., wine "C:\Program Files\Test\program.exe"). The exact steps required to reproduce the bug. Any other information you think may be relevant or helpful, such as X server version in case of X problems, libc version etc.
2. Re-run the program with the WINEDEBUG environment variable WINEDEBUG=+relay option (i.e., WINEDEBUG=+relay wine sol.exe). This will output additional information at the console that may be helpful in debugging the program. It also slows the execution of program. There are some cases where the bug seems to disappear when +relay is used. Please mention that in the bug report.
Crashes
If Wine crashes while running your program, it is important that we have this information to have a chance at guring out what is causing the crash. This can put out quite a lot (several MB) of information, though, so its best to output it to a le. When the Wine-dbg> prompt appears, type quit. You might want to try +relay,+snoop instead of +relay , but please note that +snoop is pretty unstable and often will crash earlier than a simple +relay ! If this is the case, then please use only +relay !! A bug report with a crash in +snoop code is useless in most cases! You can also turn on other parameters, depending on the nature of the problem you are researching. See wine man page for full list of the parameters. It is likely that only the last 100 or so lines of the trace are necessary to nd out where the program crashes. In order to get those last 100 lines we need to do the following 1. Redirect all the output of WINEDEBUG to a le. 2. Separate the last 100 lines to another le using tail. This can be done using one of the following methods.
27
all shells:
$ echo quit | WINEDEBUG=+relay wine [other_options] program_name >& filename.out; $ tail -n 100 filename.out > report_file
(This will print wines debug messages only to the le and then auto-quit. Its probably a good idea to use this command, since wine prints out so many debug msgs that they ood the terminal, eating CPU cycles.)
report_file will now contain the last hundred lines of the debugging output, including the register dump and
backtrace, which are the most important pieces of information. Please do not delete this part, even if you dont understand what it means. Post the bug to Wine Bugzilla (http://bugs.winehq.org/). You need to attach the output le report_file from part 2). Along with the the relevant information used to create it. Do not cut and paste the report in the bug description - it is pretty big and it will make a mess of the bug report. If you do this, your chances of receiving some sort of helpful response should be very good. Please, search the Bugzilla database to check whether your problem is already reported. If it is already reported attach the output le report_file to the original bug report and add any other relevant information.
28
Glossary
Binary A le which is in machine executable, compiled form: hex data (as opposed to a source code le).
Distribution A distribution is usually the way in which some "vendor" ships operating system CDs (usually mentioned in the context of Linux). A Linux environment can be shipped in lots of different congurations: e.g. distributions could be built to be suitable for games, scientic applications, server operation, desktop systems, etc.
DLL A DLL (Dynamic Link Library) is a le that can be loaded and executed by programs dynamically. Basically its an external code repository for programs. Since usually several different programs reuse the same DLL instead of having that code in their own le, this dramatically reduces required storage space. A synonym for a DLL would be library.
Editor An editor is usually a program to create or modify text les. There are various graphical and text mode editors available on Linux. Examples of graphical editors are: nedit, gedit, kedit, xemacs, gxedit. Examples of text mode editors are: joe, ae, emacs, vim, vi. In a terminal, simply run them via:
$ editorname
filename
Environment variable Environment variables are text denitions used in a Shell to store important system settings. In a bash shell (the most commonly used one in Linux), you can view all environment variables by executing:
set
29
Glossary
Git Git is a fast directory content manager, originally written for use with large repositories, such as the Linux Kernel source. See the Git chapter in the Wine Developers Guide for detailed usage information.
Package A package is a compressed le in a distribution specic format. It contains the les for a particular program you want to install. Packages are usually installed via the dpkg or rpm package managers.
root root is the account name of the system administrator. In order to run programs as root, simply open a Terminal window, then run:
$ su -
This will prompt you for the password of the root user of your system, and after that you will be able to system administration tasks that require special root privileges. The root account is indicated by the
#
Shell A shell is a tool to enable users to interact with the system. Usually shells are text based and command line oriented. Examples of popular shells include bash, tcsh and ksh. Wine assumes that for Wine installation tasks, you use bash, since this is the most popular shell on Linux. Shells are usually run in a Terminal window.
Source code Source code is the code that a program consists of before the program is being compiled, i.e. its the original building instructions of a program that tell a compiler what the program should look like once its been compiled to a Binary.
Terminal A terminal window is usually a graphical window that one uses to execute a Shell. If Wine asks you to open a terminal, then you usually need to click on an icon on your desktop that shows a big black window (or, in other cases, an icon displaying a maritime shell). Wine assumes youre using the bash shell in a terminal window, so if your terminal happens to use a different shell program, simply type:
bash
30