# Running Wine

This chapter will describe all aspects of running Wine, like e.g. basic Wine invocation, command line parameters of various Wine support programs etc.

## Basic usage: applications and control panel applets

Assuming you are using a fake Windows installation, you install applications into Wine in the same way you would in Windows: by running the installer. You can just accept the defaults for where to install, most installers will default to "C:\Program Files", which is fine. If the application installer requests it, you may find that Wine creates icons on your desktop and in your app menu. If that happens, you can start the app by clicking on them.

The standard way to uninstall things is for the application to provide an uninstaller, usually registered with the "Add/Remove Programs" control panel applet. To access the Wine equivalent, run the `uninstaller` program (it is located in the `programs/uninstaller/` directory in a Wine source directory) in a terminal:

            $ uninstaller

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 doesn't install menu or desktop items, you'll 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 isn't case sensitive, but remember to include the double quotes. Some programs don't always use obvious naming for their directories and EXE files, so you might have to look inside the program files directory to see what was put where.

## How to run Wine

You can invoke the `wine --help` command to get a listing of all Wine's command-line parameters:

    Usage: ./wine [options] program_name [arguments]

    Options:
       --debugmsg name  Turn debugging-messages on or off
       --help,-h        Show this help message
       --version,-v     Display the Wine version

You can specify as many options as you want, if any. Typically, you will want to have your configuration file set up with a sensible set of defaults; in this case, you can run `wine` without explicitly listing any options. In rare cases, you might want to override certain parameters on the command line.

After the options, you should put the name of the file you want `wine` to execute. If the executable is in the `Path` parameter in the configuration file, you can simply give the executable file 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:

    [wine]
    "Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"

You could run the file `c:\windows\system\foo.exe` with:

    $ wine foo.exe

However, you would have to run the file `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.

## Explorer-like graphical Wine environments

If you prefer using a graphical interface to manage your files you might want to consider using Winefile. This Winelib application comes with Wine and can be found with the other Wine programs. It is a useful way to view your drive configuration and locate files, plus you can execute programs directly from Winefile. Please note, many functions are not yet implemented.

## Wine Command Line Options

### --debugmsg [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. (As described in the Debug section of configuring wine you can modify what the `relay` trace reports). Logging does slow down Wine quite a bit, so don't use `--debugmsg` 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 `--debugmsg` option, separate them with commas. For example, to request `warn` class messages in the `heap` debug channel, you could invoke `wine` like this:

    $ wine --debugmsg warn+heap program_name

If you leave off the message class, `wine` will display messages from all four classes for that channel:

    $ wine --debugmsg +heap program_name

If you wanted to see log messages for everything except the relay channel, you might do something like this:

    $ wine --debugmsg +all,-relay 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.

### Debug Channels

accel | adpcm | advapi | animate | aspi
atom | avicap | avifile | bidi | bitblt
bitmap | cabinet | capi | caret | cdrom
cfgmgr32 | class | clipboard | clipping | combo
comboex | comm | commctrl | commdlg | computername
console | crtdll | crypt | curses | cursor
d3d | d3d_shader | d3d_surface | datetime | dc
ddeml | ddraw | ddraw_fps | ddraw_geom | ddraw_tex
debugstr | devenum | dialog | dinput | dll
dma | dmband | dmcompos | dmfile | dmfiledat
dmime | dmloader | dmscript | dmstyle | dmsynth
dmusic | dosfs | dosmem | dplay | dplayx
dpnhpast | driver | dsound | dsound3d | edit
enhmetafile | environ | event | eventlog | exec
file | fixup | font | fps | g711
gdi | global | glu | graphics | header
heap | hook | hotkey | icmp | icon
imagehlp | imagelist | imm | int | int21
int31 | io | ipaddress | iphlpapi | jack
joystick | key | keyboard | listbox | listview
loaddll | local | mapi | mci | mcianim
mciavi | mcicda | mcimidi | mciwave | mdi
menu | menubuilder | message | metafile | midi
mmaux | mmio | mmsys | mmtime | module
monthcal | mpeg3 | mpr | msacm | msdmo
msg | mshtml | msi | msimg32 | msisys
msrle32 | msvcrt | msvideo | mswsock | nativefont
netapi32 | netbios | nls | nonclient | ntdll
odbc | ole | oledlg | olerelay | opengl
pager | palette | pidl | powermgnt | print
process | profile | progress | propsheet | psapi
psdrv | qcap | quartz | ras | rebar
reg | region | relay | resource | richedit
rundll32 | sblaster | scroll | seh | selector
server | setupapi | shdocvw | shell | shlctrl
snmpapi | snoop | sound | static | statusbar
storage | stress | string | syscolor | system
tab | tape | tapi | task | text
thread | thunk | tid | timer | toolbar
toolhelp | tooltips | trackbar | treeview | ttydrv
twain | typelib | uninstaller | updown | urlmon
uxtheme | ver | virtual | vxd | wave
wc_font | win | win32 | wineboot | winecfg
wineconsole | wine_d3d | winevdm | wing | winhelp
wininet | winmm | winsock | winspool | wintab
wintab32 | wnet | x11drv | x11settings | xdnd
xrandr | xrender | xvidmode

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

### --help

Shows a small command line help page.

### --version

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

## wineserver Command Line Options

wineserver usually gets started automatically by Wine whenever the first wine process gets started. However, wineserver has some useful command line options that you can add if you start it up manually, e.g. via a user login script or so.

### -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 (not to confuse with Wine's wineserver logging channel, --debugmsg +server, though!).

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

## Setting Windows/DOS environment variables

Your program might require some environment variable to be set properly in order to run successfully. In this case you need to set this environment variable in the Linux shell, since Wine will pass on the entire shell environment variable settings to the Windows environment variable space. Example for the bash shell (other shells may have a different syntax !):

    	  export MYENVIRONMENTVAR=myenvironmentvarsetting

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/profile, or also ~/.bashrc in the case of bash.

Note however that there is an exception to the rule: If you want to change the PATH environment variable, then of course you can't modify it that way, since this will alter the Unix PATH environment setting. Instead, you should set the WINEPATH environment variable. An alternative way to indicate the content of the DOS PATH environment variable would be to change the "path" setting in the wine config file's [wine] section.

## Text mode programs (CUI: Console User Interface)

Text mode programs are program which output is only made out of text (surprise!). In Windows terminology, they are called CUI (Console User Interface) executables, by opposition to GUI (Graphical User Interface) executables. Win32 API provide a complete set of APIs to handle this situation, which goes from basic features like text printing, up to high level functionalities (like full screen editing, color support, cursor motion, mouse support), going through features like line editing or raw/cooked input stream support

Given the wide scope of features above, and the current usage in Un*x world, Wine comes out with three different ways for running a console program (aka a CUI executable):

- 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 specific Wine program (wineconsole) which provide extended facilities. The following table describes what you can do (and cannot do) with those three ways.

## Basic differences in consoles

Function | Bare streams | Wineconsole & user backend | Wineconsole & curses backend
How to run (assuming executable is called foo.exe) |
    $ wine foo.exe
    $ wineconsole -- --backend=user foo.exe
    $ wineconsole foo.exe
You can also use --backend=curses as an option
Good support for line oriented CUI applications (which print information line after line) | Yes | Yes | Yes
Good support for full screen CUI applications (including but not limited to color support, mouse support...) | No | Yes | Yes
Can be run even if X11 is not running | Yes | No | Yes
Implementation | Maps the standard Windows streams to the standard Unix streams (stdin/stdout/stderr) | Wineconsole will create a new Window (hence requiring the USER32 DLL is available) where all information will be displayed | 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
Known limitations |  |  | Will produce strange behavior if two (or more) Windows consoles are used on the same Un*x terminal.

### 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:

### Wineconsole configuration options

Configuration option | Meaning
Cursor's size | Defines the size of the cursor. Three options are available: small (33% of character height), medium (66%) and large (100%)
Popup menu | It's been said earlier that wineconsole configuration popup was triggered using a right click in the console's 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 modifiers 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.
Quick edit | 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).
History | 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).
Police | The Police property sheet allows you to pick the default font for the console (font file, size, background and foreground color).
Screenbuffer & window size | The console as you see it is made of two different parts. On one hand there's 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 screenbuffer's content.
Close on exit | If it's ticked, then the wineconsole will exit when the application within terminates. Otherwise, it'll remain opened until the user manually closes it: this allows seeing the latest information of a program after it has terminated.
Edition mode | 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: this are the standard Windows console key-bindings (mainly using arrows).