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 configuration instructions, as well as featuring extensive reference material by documenting all configuration features and support areas.

Further questions and comments

If, after examining this guide, the FAQ, and other relevant documentation there is still something you cannot figure out, we would love to hear from you. The mailing lists section contains several mailing lists and an IRC channel, all of which are great places to seek help and offer suggestions. If you are particularly savvy, and believe that something can be explained better, you can file a bug report or post a patch on Wine's documentation itself.

Content overview / Steps to take

In order to be able to use Wine, you must first have a working installation. This guide will help you to move your system from an empty, Wineless void to one boasting a fresh, up to date Wine install. The first step, Getting Wine, illustrates the various methods of getting Wine's files onto your computer. The second step, Configuring Wine, shows how to customize a Wine installation depending on your individual needs. The final step, Running Wine, covers the specific steps you can take to get a particular application to run better under Wine, and provides useful links in case you need further help.

Windows and Linux

Different software programs are designed for different operating systems, and most won't work on systems that they weren't designed for. Windows programs, for example, won't run in Linux because they contain instructions that the system can't understand until they're translated by the Windows environment. Linux programs, likewise, won't 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 difficulty: not only must the user endure the frustration of frequent rebooting, but programs for both platforms can't 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 filesystem formats, making the sharing of data between operating systems difficult.

What is Wine, and how can it help me?

Wine makes it possible to run Windows programs alongside any Unix-like operating system, particularly Linux. At its heart, Wine is an implementation of the Windows Application Programing Interface (API) library, acting as a bridge between the Windows program and Linux. Think of Wine as a compatibility layer, when a Windows program tries to perform a function that Linux doesn't normally understand, Wine will translate that program's instruction into one supported by the system. For example, if a program asks the system to create a Windows pushbutton or text-edit field, Wine will convert that instruction into its Linux equivalent in the form of a command to the window manager using the standard X11 protocol.

If you have access to the Windows program's source code, Wine can also be used to recompile a program into a format that Linux can understand more easily. Wine is still needed to launch the program in its recompiled form, however there are many advantages to compiling a Windows program natively within Linux. For more information, see the Winelib User Guide.

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 files (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

• 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 configurable trace logging messages for easier troubleshooting

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 intermittant releases (roughly once 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 on the CVS server. See the next chapter, Getting Wine, for further details.

Other Versions of Wine

There are a number of programs that are derived from the standard Wine codebase in some way or another. Some of these are commercial products from companies that actively contribute to the Wine project.

These products try to stand out or distinguish themselves from the standard version of Wine by offering greater compatibility, easier configuration, and commercial support. If you require such things, it is a good idea to consider purchasing these products.

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 filesharing 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.

Another Operating System

Probably the most obvious method of getting a Windows application to run is to simply run it on Windows. However, security, license cost, backward-compatibility, and machine efficiency issues can make this a difficult proposition, which is why Wine is so useful in the first place.

Another alternative is to use ReactOS, which is a fully open source alternative to Windows. ReactOS shares code heavily with the Wine project, but rather than running Windows applications on top of Linux they are instead run on top of the ReactOS kernel. ReactOS also offers compatibility with Windows driver files, allowing the use of hardware without functional Linux drivers.

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 and QEMU can run both Windows and ReactOS virtually. Other, commercial virtual machine offerings include VMware and Microsoft's VirtualPC.

There are significant 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 won't, 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.

Installation from a package

By far the easiest method for installing Wine is to use a prepackaged version of Wine. These packages contain ready-to-run Wine binary files specifically compiled for your distribution, and they are tested regularly by the packagers for both functionality and completeness.

Packages are the recommended method for installing Wine. We make them easily available at the WineHQ downloads page , and these are always the latest packages available. Being popular, Wine packages can also be found elsewhere in official distribution repositories. These can, however, sometimes be out of date, depending on the distribution. Packages are easily upgradable as well, and many distributions can upgrade Wine seamlessly with a few clicks. Building your own installable binary package from a source package is also possible, although it is beyond the scope of this guide.

Installation from a source archive

Sometimes the Wine packages don't fit your needs exactly. Perhaps they're not available for your architecture or distribution, or perhaps you want to build wine using your own compiler optimizations or with some options disabled, or perhaps you need to modify a specific part of the source code before compilation. Being an open source project, you are free to do all of these things with Wine's source code, which is provided with every Wine release. This method of installation can be done by downloading a Wine source archive and compiling from the command line. If you are comfortable with such things and have special needs, this option may be for you.

Getting Wine source archives is simple. Every release, we put a source package in compressed tar.gz format at the WineHQ downloads page. Compiling and installing Wine from source is slightly more difficult than using a package, however we will cover it in depth and attempt to hold your hand along the way.

Installation from a cvs snapshot

If you wish to try out the bleeding edge of Wine development, or would even like to help develop Wine yourself, you can download the very latest source code from our CVS server. Instructions for downloading from the Wine cvs repository are available at http://www.winehq.org/site/cvs .

Please take note that the usual warnings for using a developmental version still apply. The source code on the CVS server is largely untested and may not even compile properly. It is, however, the best way to test out how Wine will work in the next version, and if you're modifying source code it's best to get the latest copy. The CVS repository is also useful for application maintainers interested in testing if an application will still work right for the next release, or if a recent patch actually improves things. If you're interested in helping us to get an application working in Wine, see the guide to helping applications work.

Installing a fresh package

Installing a package on a fresh system is remarkably straightforward. Simply download and install the package using whatever utility your distribution provides. There is usually no need to explicitly remove old packages before installing, as modern Linux distributions should upgrade and replace them automatically. If you installed Wine from source code, however, you should remove it before installing a Wine package. See the section on uninstalling Wine from source for proper instructions.

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 specific way of installing and managing packages. Fortunately, however, the same general ideas apply to all of them, and installing Wine should be no more difficult 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 won't cover the specifics 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. If you need further help figuring out how to simply install a Wine package, we suggest consulting your distribution's documentation, support forums, or IRC channels.

Getting the Build Dependencies

Wine makes use of many open source libraries during its operation. While Wine is not strictly dependent on these libraries and will compile without most of them, much of Wine's functionality is improved by having them available at compile time. In the past, many user problems were caused by people not having the necessary development libraries when they built Wine from source; because of this reason and others, we highly recommend installing via binary packages or by building source packages which can automatically satisfy their build dependencies.

If you wish to install build dependencies by hand, there are several ways to see if you're missing some useful development libraries. The most straightforward approach is to watch the configure program's output before you compile Wine and see if anything important is missing; if it is, simply install what's missing and rerun configure before compiling. You can also check the file configure generates, (include/config.h.in) and see if what files configure is looking for but not finding.

Compiling Wine

Once you've installed the build dependencies you need, you're ready to compile the package. In the terminal window, after having navigated to the Wine source tree, run the following commands:

            $ ./configure
            # make depend
            # make
            # make install
            

Uninstalling Wine from Source

To uninstall Wine from source, once again navigate to the same source folder that you used to install Wine using the terminal. Then, run the following command:

            # make uninstall
            

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 specific behavior in order to function and changing this setting may cause a buggy app to work. Recently Wine's default Windows version has changed to Windows 2000. It's known that many applications will perform better if you choose Windows 98.

Within the tab you'll notice there is a Default Settings entry. If you select that you'll see the current default Windows Version for all applications. A troublesome application is best configured separately from the Default Settings. To do that:

1. Click on the Add application button.

2. Browse until you locate the .exe

3. After it's been added you can choose the specific Windows version Wine will emulate for that application.

Libraries Settings

Likewise, some applications require specific libraries in order to run. Wine reproduces the Windows system libraries (so-called native DLL's) with completely custom versions designed to function exactly the same way but without requiring licenses from Microsoft. Wine has many known deficiencies in it's built-in versions, but in many instances the functionality is sufficient. Using only builtin DLL's ensures that your system is Microsoft-free. However, Wine has the ability to load native Windows DLL's.

Graphics Settings

There are basically five different graphics settings you can configure. For most people the defaults are fine.

The first is the "screen color depth" and represents the number of colors that can be displayed on the screen. Older graphics cards had a hard time displaying a full-range of colors and for them it's useful to be able to specify an "8-bit" display. Modern video cards, namely anything with over 8MB of memory, have no problem using a full 24 or 32-bit depth.

The next 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. There's lots of reasons you might want to do that, not the least of which includes it's easier to play the game if the cursor is confined 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 benefit from, and the default is to leave it turned on. The tradeoff is increased memory use.

You may find it helpful to Emulate a virtual desktop. In this case, all programs will run in a separate window. You may find this useful as a way to test buggy games that change (possibly unsuccessfully) the screen resolution. Confining 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 configure some Direct3D settings. For the most part these settings are detected automatically, but you can force them to behave in a specific manner. Some games attempt to probe the underlying system to see if it supports specific features. By turning these off Wine won't 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 configuration that Wine imitates. Most people are familiar with the standard notation of the "A:" drive representing the floppy disk, the "C:" drive representing the primary system disk, etc. Wine uses the same concept and maps those drives to the underlying native filesystem.

Wine's drive configuration is relatively simple. In Winecfg under the Drives tab you'll 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 what's in the Path: box. If you're 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. It's recommended you try this before attempting to configure drives manually. Simply click on the Autodetect button to have Wine search for drives on your system.

You may be interested in configuring your drive settings outside of Winecfg, in which case you're in luck because it's 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 first time you run Wine:

             $ ls -la ~/.wine/dosdevices/
             lrwxrwxrwx  1 wineuser wineuser   10 Jul 23 15:12 c: -> ../drive_c
             lrwxrwxrwx  1 wineuser wineuser    1 Jul 23 15:12 z: -> /
           

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\system to mean ~/.wine/drive_c/windows/system.

Audio Settings

Wine can work with quite a few different audio subsystems which you can choose under the "Audio" tab. The "Autodetect" button can figure it all out for you, or you can manually select a driver. Older Linux distributions using the 2.4 kernel or earlier typically use the "OSS" driver. Newer 2.6 kernels have switched to "ALSA". If you're using KDE, regardless of the kernel, you can probably also use "aRts". If you're using GNOME you can probably use EsounD. The OSS and ALSA audio drivers get the most testing, so it's recommended you stick with them if possible. If you need to use "Jack" or "NAS" you probably already know why.

DirectSound settings are primarily used by games. You can choose what level of hardware acceleration you'd like, but for most people "Full" is fine.

Appearance

Wine can load Windows themes if you have them available. While this certainly isn't 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 files 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 you'd like to try this out:

1. Download a Windows XP theme. Be sure it contains a .msstyles file.

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 new Appearance tab of winecfg to select the new theme.

Registry Structure

Okay.. with that out of the way, let's dig into the registry a bit to see how it's 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:

Registry Files

Now, what you're probably wondering is how that translates into Wine's structure. The registry layout described above actually lives in three different files within each user's ~/.wine directory:

These files are automatically created by wineprefixcreate the first time you use Wine. A set of global settings is stored in the c:\windows\inf\wine.inf and is processed by the rundll32.exe program. The first time you run Wine the wine.inf file gets processed to populate the initial registry. For more details, check out the wineprefixcreate script to see how it's all done. After updating Wine, wineprefixcreate can also be used to update the default registry entries.

Like we mentioned, you can edit those .reg files using whatever text editor you want. Just make sure Wine isn't 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 and it should pop up. You'll immediately notice that the cryptic keys displayed in the text file 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.

System Administration Tips

With the above file structure, it is possible for a system administrator to configure the system so that a system Wine installation (and applications) can be shared by all the users, and still let the users all have their own personalized configuration. An administrator can, after having installed Wine and any Windows application software he wants the users to have access to, copy the resulting system.reg and over to the global registry files (which we assume will reside in /usr/local/etc here), with:

          cd ~root/.wine
          cp system.reg /usr/local/etc/wine.systemreg
        

and perhaps even symlink these back to the administrator's 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 file contains user specific settings. Every user should have their own copy of that file along with the permissions to modify it.

You'll want to pay attention to drive mappings. If you're sharing the system.reg file you'll 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 configuration provided by wineprefixcreate, 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 specific 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 final word of caution: be careful with what you do with the administrator account - if you do copy or link the administrator's registry to the global registry, any user might be able to read the administrator's 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.

Complete List of Registry Keys

You'll find an up-to-date list of useful registry keys and values in the developer's wiki.

Serial and Parallel Ports

Serial and parallel port configuration is very similar to drive configuration - simply create a symbolic link in ~/.wine/dosdevices with the name of the device. Windows serial ports follow a naming convention of the word "com" followed by a number, such as com1, com2, etc. Similarly, parallel ports use "lpt" followed by a number, such as lpt1. You should link these directly to the corresponding Unix devices, such as /dev/ttyS0 and /dev/lp0. For example, to configure one serial port and one parallel port, run the following commands:

          ln -s /dev/ttyS0 com1
          ln -s /dev/lp0 lpt1
        

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
          

Fonts

Font configuration, once a nasty problem, is now much simpler. If you have a collection of TrueType fonts in Windows it's simply a matter of copying the .ttf files into c:\windows\fonts.

Printers

Wine can interact directly with the CUPS printing system to find the printers available on your system. Configuring printers with Wine is as simple as making sure your CUPS configuration works.

Scanners

In Windows, scanners use the TWAIN API to access the underlying hardware. Wine's builtin TWAIN DLL simply forwards those requests to the Linux SANE libraries. So, to utilize your scanner under Wine you'll first need to make sure you can access it using SANE. After that you'll 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 find it works for you, please consider updating this section of the user guide to provide details on using SANE with Wine.

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 configure 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 configure Wine to use the native odbc32.dll it will try to use the native ODBC32 drivers etc.

          export LIB_ODBC_DRIVER_MANAGER=/usr/lib/libodbc.so.1.0.0
        

        $ ln -s libodbc.so.1.0.0 /usr/lib/libodbc.so
        $ /sbin/ldconfig
        

--help

Shows a small command line help page.

--version

Shows the Wine version string. Useful to verify your installation.

WINEDEBUG=[channels]

Wine isn't perfect, and many Windows applications still don't run without bugs under Wine (but then, a lot of programs don't 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 file and examine it at your leisure. But be forewarned! Some debug channels can generate incredible volumes of log messages. Among the most prolific 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. (You'll want to check out RelayExclude registry key to modify what the relay trace reports). Logging does slow down Wine quite a bit, so don't use WINEDEBUG unless you really do want log files.

Within each debug channel, you can further specify a message class, to filter 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:

$ WINEDEBUG=warn+heap wine program_name
        

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.

For more details about debug channels, check out the The Wine Developer's Guide.

WINEDLLOVERRIDES=[DLL Overrides]

It's not always possible to run an application on builtin DLL's. Sometimes native DLL's 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 informations about DLL overrides, please refer to the DLL overrides section of this guide.

-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 specific 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 it's 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.

Configuration of CUI executables

When wineconsole is used, several configuration options are available. Wine (as Windows do) stores, on a per application basis, several options in the registry. This let a user, for example, define the default screen-buffer size he would like to have for a given application.

As of today, only the USER backend allows you to edit those options (we don't recommend editing by hand the registry contents). This edition is fired when a user right click in the console (this popups a menu), where you can either choose from:

• Default: this will edit the settings shared by all applications which haven't been configured yet. So, when an application is first 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 you'll be able to modify at your will.

  Properties: this will edit the application's settings. When you're done, with the edition, you'll be prompted whether you want to:

  1. Keep these modified settings only for this session (next time you run the application, you will not see the modification you've just made).

  2. Use the settings for this session and save them as well, so that next you run your application, you'll use these new settings again.

Here's the list of the items you can configure, and their meanings:

Verify your wine configuration

Look at the output from $ wine --version to make sure you're running a recent version of Wine. Launch winecfg and look over the settings to make sure you have settings that look normal. Look in ~/.wine/dosdevices to make sure you're c: points to where you think it should.

Use different windows version settings

In several cases using different windows version settings can help.

Use different startup paths

This sometimes helps, too: Try to use both wine prg.exe and wine x:\\full\\path\\to\\prg.exe

Fiddle with DLL configuration

Run with WINEDEBUG=+loaddll to figure out which DLLs are being used, and whether they're being loaded as native or built-in. 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.

Check your system environment !

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 !)

Use different GUI (Window Manager) modes

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.

Check your app !

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).

Go to GameCopyWorld 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... :-)

Check your Wine environment !

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.

Reconfigure 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 that's recommended for your Wine distribution to create new configuration. Use information in old ~/.wine 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 ~/.wine directory and rename your old one back.

Check out further information

There is a really good chance that someone has already tried to do the same thing as you. You may find the following resources helpful:

• Search WineHQ's Application Database to check for any tips relating to the program. If your specific version of the program isn't listed you may find a different one contains enough information to help you out.

• Frank's Corner contains a list of applications and detailed instructions for setting them up. Further help can be found in the user forums.

• Google can be useful depending on how you use it. You may find it helpful to search Google Groups, in particular the comp.emulators.ms-windows.wine group.

• Freenode.net hosts an IRC channel for Wine. You can access it by using any IRC client such as Xchat. The settings you'll need are: server = irc.freenode.net, port = 6667, and channel = #winehq

• If you have a program that needs the Visual Basic Runtime Environment, you can download it from this Microsoft site

• If you know you are missing a DLL, such as mfc42, you may be able to find it at www.dll-files.com

• Wine's mailing lists may also help, especially wine-users. The wine-devel list may be appropriate depending on the type of problem you are experiencing. If you post to wine-devel you should be prepared to do a little work to help diagnose the problem. Read the section below to find out how to debug the source of your problem.

• If all else fails, you may wish to investigate commercial versions of Wine to see if your application is supported.

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 configurations issues to completely unimplemented functionality in Wine. The next section will describe how to file a bug report and how to begin debugging a crash. For more information on using Wine's debugging facilities be sure to read the Wine Developers Guide.

All Bug Reports

Some simple advice on making your bug report more useful (and thus more likely to get answered and fixed):

1. Post as much relevant information as possible.

   This means we need more information than a simple "MS Word crashes whenever I run it. Do you know why?" Include at least the following information:

   • Which version of Wine you're using (run wine --version)

   • The name of the Operating system you're using, what distribution (if any), and what version. (i.e., Linux Red Hat 7.2)

   • Which compiler and version, (run gcc -v). If you didn't compile wine then the name of the package and where you got it from.

   • Windows version, if used with Wine. Mention if you don't use Windows.

   • The name of the program you're 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 figuring out what is causing the crash. This can put out quite a lot (several MB) of information, though, so it's best to output it to a file. 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.

To get the trace output, use one of the following methods: