2 <title>Running Wine</title>
5 Written by &name-john-sheets; <email>&email-john-sheets;</email>
8 Extended by &name-mike-hearn; <email>&email-mike-hearn;</email>, &name-eric-pouech; <email>&email-eric-pouech;</email>
9 Modified by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
13 This chapter will describe all aspects of running Wine, like e.g.
14 basic Wine invocation, command line parameters of various Wine
18 <sect1 id="basic-usage">
19 <title>Basic usage: applications and control panel applets</title>
21 Assuming you are using a fake Windows installation, you install
22 applications into Wine in the same way you would in Windows: by
23 running the installer. You can just accept the defaults for
24 where to install, most installers will default to "C:\Program
25 Files", which is fine. If the application installer requests it,
26 you may find that Wine creates icons on your desktop and in your
27 app menu. If that happens, you can start the app by clicking on
32 The standard way to uninstall things is for the application to
33 provide an uninstaller, usually registered with the "Add/Remove
34 Programs" control panel applet.
35 To access the Wine equivalent, run the <command>uninstaller</command>
36 program (it is located in the
37 <filename>programs/uninstaller/</filename> directory in a Wine
38 source directory) in a <glossterm>terminal</glossterm>:
42 <prompt>$</prompt> <userinput>uninstaller</userinput>
46 Some programs install associated control panel applets, examples
47 of this would be Internet Explorer and QuickTime. You can access
48 the Wine control panel by running in a
49 <glossterm>terminal</glossterm>:
53 <prompt>$</prompt> <userinput>wine control</userinput>
57 which will open a window with the installed control panel
58 applets in it, as in Windows.
62 If the application doesn't install menu or desktop items, you'll
63 need to run the app from the command line. Remembering where you
64 installed to, something like:
68 <prompt>$</prompt> <userinput>wine "c:\program files\appname\appname.exe"</userinput>
72 will probably do the trick. The path isn't case sensitive, but
73 remember to include the double quotes. Some programs don't
74 always use obvious naming for their directories and EXE files,
75 so you might have to look inside the program files directory to
80 <sect1 id="running-wine">
81 <title>How to run Wine</title>
83 Wine is a very complicated piece of software with many ways to
84 adjust how it runs. With very few exceptions, you can
85 activate the same set of features through the <link
86 linkend="config-file">configuration file</link> as you can
87 with command-line parameters. In this chapter, we'll briefly
88 discuss these parameters, and match them up with their
89 corresponding configuration variables.
93 You can invoke the <command>wine --help</command> command to
94 get a listing of all Wine's command-line parameters:
98 Usage: ./wine [options] program_name [arguments]
101 --debugmsg name Turn debugging-messages on or off
102 --dll name Enable or disable built-in DLLs
103 --help,-h Show this help message
104 --version,-v Display the Wine version
109 You can specify as many options as you want, if any.
110 Typically, you will want to have your configuration file set
111 up with a sensible set of defaults; in this case, you can run
112 <command>wine</command> without explicitly listing any
113 options. In rare cases, you might want to override certain
114 parameters on the command line.
117 After the options, you should put the name of the file you
118 want <command>wine</command> to execute. If the executable is
119 in the <parameter>Path</parameter> parameter in the
120 configuration file, you can simply give the executable file
121 name. However, if the executable is not in
122 <parameter>Path</parameter>, you must give the full path to
123 the executable (in Windows format, not UNIX format!). For
124 example, given a <parameter>Path</parameter> of the following:
128 "Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"
131 You could run the file
132 <filename>c:\windows\system\foo.exe</filename> with:
135 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
138 However, you would have to run the file
139 <filename>c:\myapps\foo.exe</filename> with this command:
142 <prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
145 (note the backslash-escaped "\" !)
148 For details on running text mode (CUI) executables, read the
149 <link linkend="CUI-programs">section</link> below.
154 <title>Explorer-like graphical Wine environments</title>
157 If you don't feel like manually invoking Wine for every program
158 you want to run and instead want to have an integrated graphical
159 interface to run your Windows programs in, then installing e.g.
160 <ulink url="http://www.calmira.org">Calmira</ulink>, a
161 Win95-Explorer-like shell replacement, would probably be a great
162 idea. Calmira might still have a few problems running on Wine,
163 though. Other usable Explorer replacements should be listed here
168 <sect1 id="command-line-options">
169 <title>Wine Command Line Options</title>
171 <sect2 id="config-parameter">
172 <title>--debugmsg [channels]</title>
174 Wine isn't perfect, and many Windows applications still
175 don't run without bugs under Wine (but then, a lot of programs
176 don't run without bugs under native Windows either!). To
177 make it easier for people to track down the causes behind
178 each bug, Wine provides a number of <firstterm>debug
179 channels</firstterm> that you can tap into.
182 Each debug channel, when activated, will trigger logging
183 messages to be displayed to the console where you invoked
184 <command>wine</command>. From there you can redirect the
185 messages to a file and examine it at your leisure. But be
186 forewarned! Some debug channels can generate incredible
187 volumes of log messages. Among the most prolific offenders
188 are <parameter>relay</parameter> which spits out a log
189 message every time a win32 function is called,
190 <parameter>win</parameter> which tracks windows message
191 passing, and of course <parameter>all</parameter> which is
192 an alias for every single debug channel that exists. For a
193 complex application, your debug logs can easily top 1 MB and
194 higher. A <parameter>relay</parameter> trace can often
195 generate more than 10 MB of log messages, depending on how
196 long you run the application. (As described in the
197 <link linkend = "config-debug-etc">Debug</link>
198 section of configuring wine you can
199 modify what the <parameter>relay</parameter> trace reports).
200 Logging does slow down Wine
201 quite a bit, so don't use <parameter>--debugmsg</parameter>
202 unless you really do want log files.
205 Within each debug channel, you can further specify a
206 <firstterm>message class</firstterm>, to filter out the
207 different severities of errors. The four message classes
209 <simplelist type="inline">
210 <member><parameter>trace</parameter></member>
211 <member><parameter>fixme</parameter></member>
212 <member><parameter>warn</parameter></member>
213 <member><parameter>err</parameter></member>
217 To turn on a debug channel, use the form
218 <parameter>class+channel</parameter>. To turn it off, use
219 <parameter>class-channel</parameter>. To list more than one
220 channel in the same <parameter>--debugmsg</parameter>
221 option, separate them with commas. For example, to request
222 <parameter>warn</parameter> class messages in the
223 <parameter>heap</parameter> debug channel, you could invoke
224 <command>wine</command> like this:
227 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
230 If you leave off the message class, <command>wine</command>
231 will display messages from all four classes for that channel:
234 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
237 If you wanted to see log messages for everything except the
238 relay channel, you might do something like this:
241 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
244 Here is a list of the debug channels and classes in Wine.
245 More channels will be added to (or subtracted from) later
249 <table frame="none"><title>Debug Channels</title>
250 <tgroup cols=5 align="left">
253 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
255 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
257 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
259 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
261 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
263 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
265 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
267 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
269 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
271 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
273 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
275 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
277 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
279 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
281 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
283 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
285 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
287 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
289 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
291 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
293 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
295 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
297 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
299 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
301 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
303 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
305 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
307 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
309 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
311 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
313 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
315 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
317 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
319 winspool</><entry>wnet</><entry>x11</>
326 For more details about debug channels, check out the
327 <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
328 The Wine Developer's Guide</ulink>.
335 Specifies whether to load the builtin or the native (if
336 available) version of a DLL.
339 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
341 See the <link linkend="config-dll">DLL chapter</link> for more details.
346 <title>--help</title>
348 Shows a small command line help page.
353 <title>--version</title>
355 Shows the Wine version string. Useful to verify your installation.
360 <sect1 id="wineserver-command-line-options">
361 <title>wineserver Command Line Options</title>
364 wineserver usually gets started automatically by Wine whenever
365 the first wine process gets started.
366 However, wineserver has some useful command line options that
367 you can add if you start it up manually, e.g. via a user login
371 <sect2 id="wineserver-config-parameter">
372 <title>-d<n></title>
374 Sets the debug level for debug output in the terminal that
375 wineserver got started in at level <n>.
376 In other words: everything greater than 0 will enable
377 wineserver specific debugging output (not to confuse with Wine's wineserver logging channel, --debugmsg +server, though!).
384 Display wineserver command line options help message.
391 Kill the current wineserver, optionally with signal n.
398 This parameter makes wineserver persistent, optionally for n
399 seconds. It will prevent wineserver from shutting down immediately.
402 Usually, wineserver quits almost immediately after the last
403 wine process using this wineserver terminated.
404 However, since wineserver loads a lot of things on startup
405 (such as the whole Windows registry data), its startup might
406 be so slow that it's very useful to keep it from exiting after
407 the end of all Wine sessions, by making it persistent.
414 This parameter makes a newly started wineserver wait until the
415 currently active wineserver instance terminates.
420 <sect1 id="environment-variables">
421 <title>Setting Windows/DOS environment variables</title>
423 Your program might require some environment variable to be set
424 properly in order to run successfully.
425 In this case you need to set this environment variable in the
426 Linux shell, since Wine will pass on the entire shell environment
427 variable settings to the Windows environment variable space.
428 Example for the bash shell (other shells may have a different syntax
431 export MYENVIRONMENTVAR=myenvironmentvarsetting
433 This will make sure your Windows program can access the
434 MYENVIRONMENTVAR environment variable once you start your program
436 If you want to have MYENVIRONMENTVAR set permanently, then you can
437 place the setting into /etc/profile, or also ~/.bashrc in the case of
441 Note however that there is an exception to the rule:
442 If you want to change the PATH environment variable, then of
443 course you can't modify it that way, since this will alter the
444 Unix PATH environment setting. Instead, you should set the
445 WINEPATH environment variable. An alternative way to
446 indicate the content of the DOS PATH environment variable would
447 be to change the "path" setting in the wine config file's <link
448 linkend="config-wine">[wine]</link> section.
453 <sect1 id="CUI-programs">
454 <title>Text mode programs (CUI: Console User Interface)</title>
455 <para>Text mode programs are program which output is only made
456 out of text (surprise!). In Windows terminolgy, they are
457 called CUI (Console User Interface) executables, by opposition
458 to GUI (Graphical User Interface) executables. Win32 API
459 provide a complete set of APIs to handle this situation, which
460 goes from basic features like text printing, up to high level
461 functionnalities (like full screen editing, color support,
462 cursor motion, mouse support), going through features like
463 line editing or raw/cooked input stream support
466 Given the wide scope of features above, and the current usage
467 in Un*x world, Wine comes out with three different ways for
468 running a console program (aka a CUI executable):
471 <para>bare streams</para>
474 <para>wineconsole with user backend</para>
477 <para>wineconsole with curses backend</para>
481 <para>The names here are a bit obscure. "bare streams" means
482 that no extra support of wine is provide to map between the
483 unix console access and Windows console access. The two other
484 ways require the use of a specific Wine program (wineconsole)
485 which provide extended facilities. The following table
486 describes what you can do (and cannot do) with those three
489 <title>Basic differences in consoles</title>
490 <tgroup cols="4" align="left">
493 <entry>Function</entry>
494 <entry>Bare streams</entry>
495 <entry>Wineconsole & user backend</entry>
496 <entry>Wineconsole & curses backend</entry>
501 <entry>How to run (assuming executable is called foo.exe)</entry>
503 <screen><prompt>$</prompt> <userinput>wine foo.exe</userinput></screen>
506 <screen><prompt>$</prompt> <userinput>wineconsole -- --backend=user foo.exe</userinput></screen>
509 <screen><prompt>$</prompt> <userinput>wineconsole foo.exe</userinput></screen>
510 </msgtext>You can also use --backend=curses as an option</entry>
513 <entry>Good support for line oriented CUI applications
514 (which print information line after line)
521 <entry>Good support for full screen CUI
522 applications (including but not limited to color
523 support, mouse support...)</entry>
529 <entry>Can be run even if X11 is not running</entry>
535 <entry>Implementation</entry>
536 <entry>Maps the standard Windows streams to the
537 standard Unix streams (stdin/stdout/stderr)
540 Wineconsole will create a new Window (hence
541 requiring the USER32 DLL is available) where all
542 information will be displayed
545 Wineconsole will use existing unix console
546 (from which the program is run) and with the help of
547 the (n)curses library take control of all the terminal
548 surface for interacting with the user
552 <entry>Known limitations</entry>
556 Will produce strange behavior if two (or more)
557 Windows consoles are used on the same Un*x terminal.
564 <sect2 id="CUI-programs-config">
565 <title>Configuration of CUI executables</title>
567 When wineconsole is used, several configuration options are
568 available. Wine (as Windows do) stores, on a per application
569 basis, several options in the registry. This let a user, for
570 example, define the default screen-buffer size he would like
571 to have for a given application.
574 As of today, only the USER backend allows you to edit those
575 options (we don't recommend editing by hand the registry
576 contents). This edition is fired when a user right click in
577 the console (this popups a menu), where you can either
582 Default: this will edit the settings shared by all
583 applications which haven't been configured yet. So,
584 when an application is first run (on your machine,
585 under your account) in wineconsole, wineconsole will
586 inherit this default settings for the
587 application. Afterwards, the application will have its
588 own settings, that you'll be able to modify at your will.
591 Properties: this will edit the application's
592 settings. When you're done, with the edition, you'll
593 be prompted whether you want to:
597 Keep these modified settings only for this
598 session (next time you run the application, you
599 will not see the modification you've just made).
604 Use the settings for this session and save them
605 as well, so that next you run your application,
606 you'll use these new settings again.
615 Here's the list of the items you can configure, and their
618 <title>Wineconsole configuration options</title>
619 <tgroup cols="2" align="left">
622 <entry>Configuration option</entry>
623 <entry>Meaning</entry>
628 <entry>Cursor's size</entry>
630 Defines the size of the cursor. Three options are
631 available: small (33% of character height), medium
632 (66%) and large (100%)
636 <entry>Popup menu</entry>
638 It's been said earlier that wineconsole
639 configuration popup was triggered using a right
640 click in the console's window. However, this can
641 be an issue when the application you run inside
642 wineconsole expects the right click events to be
643 sent to it. By ticking control or shift you select
644 additional modifiers on the right click for
645 opening the popup. For example, ticking shift will
646 send events to the application when you right
647 click the window without shift being hold down,
648 and open the window when you right-click while
649 shift being hold down.
653 <entry>Quick edit</entry>
655 This tick box lets you decide whether left-click
656 mouse events shall be interpreted as events to be
657 sent to the underlying application (tick off) or
658 as a selection of rectangular part of the screen
659 to be later on copied onto the clipboard (tick on).
663 <entry>History</entry>
665 This lets you pick up how many commands you want
666 the console to recall. You can also drive whether
667 you want, when entering several times the same
668 command - potentially intertwened with others -
669 whether you want to store all of them (tick off)
670 or only the last one (tick on).
674 <entry>Police</entry>
676 The Police property sheet allows you to pick the
677 default font for the console (font file, size,
678 background and foreground color).
682 <entry>Screenbuffer & window size</entry>
684 The console as you see it is made of two different
685 parts. On one hand there's the screenbuffer which
686 contains all the information your application puts
687 on the screen, and the window which displays a
688 given area of this screen buffer. Note that the
689 window is always smaller or of the same size than
690 the screen buffer. Having a stricly smaller window
691 size will put on scrollbars on the window so that
692 you can see the whole screenbuffer's content.
696 <entry>Close on exit</entry>
698 If it's ticked, then the wineconsole will exit
699 when the application within terminates. Otherwise,
700 it'll remain opened until the user manually closes
701 it: this allows seeing the latest information of a
702 program after it has terminated.
706 <entry>Edition mode</entry>
710 When the user enter commands, he or she can
711 choose between several edition modes:
715 Emacs: the same keybindings as under
716 emacs are available. For example, Ctrl-A
717 will bring the cursor to the beginning
718 of the edition line. See your emacs
719 manual for the details of the commands.
724 Win32: this are the standard Windows
725 console key-bindings (mainly using
742 <!-- Keep this comment at the end of the file
745 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
projects / wine / blob