2 <title>Running Wine</title>
5 Written by &name-john-sheets; <email>&email-john-sheets;</email>
6 Modified by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
9 Extended by &name-mike-hearn; <email>&email-mike-hearn;</email>, &name-eric-pouech; <email>&email-eric-pouech;</email>
10 Modified by &name-andreas-mohr; <email>&email-andreas-mohr;</email>
14 This chapter will describe all aspects of running Wine, like e.g.
15 basic Wine invocation, command line parameters of various Wine
20 This chapter will describe all aspects of running Wine, like e.g.
21 basic Wine invocation, command line parameters of various Wine
29 <sect1 id="basic-usage">
30 <title>Basic usage: applications and control panel applets</title>
32 Assuming you are using a fake Windows installation, you install
33 applications into Wine in the same way you would in Windows: by
34 running the installer. You can just accept the defaults for
35 where to install, most installers will default to "C:\Program
36 Files", which is fine. If the application installer requests it,
37 you may find that Wine creates icons on your desktop and in your
38 app menu. If that happens, you can start the app by clicking on
43 The standard way to uninstall things is for the application to
44 provide an uninstaller, usually registered with the "Add/Remove
45 Programs" control panel applet.
46 To access the Wine equivalent, run the <command>uninstaller</command>
47 program (it is located in the
48 <filename>programs/uninstaller/</filename> directory in a Wine
49 source directory) in a <glossterm>terminal</glossterm>:
53 <prompt>$</prompt> <userinput>uninstaller</userinput>
57 Some programs install associated control panel applets, examples
58 of this would be Internet Explorer and QuickTime. You can access
59 the Wine control panel by running in a
60 <glossterm>terminal</glossterm>:
64 <prompt>$</prompt> <userinput>wine control</userinput>
68 which will open a window with the installed control panel
69 applets in it, as in Windows.
73 If the application doesn't install menu or desktop items, you'll
74 need to run the app from the command line. Remembering where you
75 installed to, something like:
79 <prompt>$</prompt> <userinput>wine "c:\program files\appname\appname.exe"</userinput>
83 will probably do the trick. The path isn't case sensitive, but
84 remember to include the double quotes. Some programs don't
85 always use obvious naming for their directories and EXE files,
86 so you might have to look inside the program files directory to
87 see what it put where.
91 <sect1 id="running-wine">
92 <title>How to run Wine</title>
94 Wine is a very complicated piece of software with many ways to
95 adjust how it runs. With very few exceptions, you can
96 activate the same set of features through the <link
97 linkend="config-file">configuration file</link> as you can
98 with command-line parameters. In this chapter, we'll briefly
99 discuss these parameters, and match them up with their
100 corresponding configuration variables.
104 You can invoke the <command>wine --help</command> command to
105 get a listing of all Wine's command-line parameters:
109 Usage: ./wine [options] program_name [arguments]
112 --debugmsg name Turn debugging-messages on or off
113 --dll name Enable or disable built-in DLLs
114 --help,-h Show this help message
115 --version,-v Display the Wine version
120 You can specify as many options as you want, if any.
121 Typically, you will want to have your configuration file set
122 up with a sensible set of defaults; in this case, you can run
123 <command>wine</command> without explicitly listing any
124 options. In rare cases, you might want to override certain
125 parameters on the command line.
128 After the options, you should put the name of the file you
129 want <command>wine</command> to execute. If the executable is
130 in the <parameter>Path</parameter> parameter in the
131 configuration file, you can simply give the executable file
132 name. However, if the executable is not in
133 <parameter>Path</parameter>, you must give the full path to
134 the executable (in Windows format, not UNIX format!). For
135 example, given a <parameter>Path</parameter> of the following:
139 "Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"
142 You could run the file
143 <filename>c:\windows\system\foo.exe</filename> with:
146 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
149 However, you would have to run the file
150 <filename>c:\myapps\foo.exe</filename> with this command:
153 <prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
156 (note the backslash-escaped "\" !)
159 For details on running text mode (CUI) executables, read the
160 <link linkend="CUI-programs">section</link> below.
164 <sect1 id="explorer-like-wine">
165 <title>Explorer-like graphical Wine environments</title>
168 If you don't feel like manually invoking Wine for every program
169 you want to run and instead want to have an integrated graphical
170 interface to run your Windows programs in, then installing e.g.
171 <ulink url="http://www.calmira.org">Calmira</ulink>, a
172 Win95-Explorer-like shell replacement, would probably be a great
173 idea. Calmira might still have a few problems running on Wine,
174 though. Other usable Explorer replacements should be listed here
179 <sect1 id="command-line-options">
180 <title>Wine Command Line Options</title>
182 <sect2 id="config-parameter">
183 <title>--debugmsg [channels]</title>
185 Wine isn't perfect, and many Windows applications still
186 don't run without bugs under Wine (but then, a lot of programs
187 don't run without bugs under native Windows either!). To
188 make it easier for people to track down the causes behind
189 each bug, Wine provides a number of <firstterm>debug
190 channels</firstterm> that you can tap into.
193 Each debug channel, when activated, will trigger logging
194 messages to be displayed to the console where you invoked
195 <command>wine</command>. From there you can redirect the
196 messages to a file and examine it at your leisure. But be
197 forewarned! Some debug channels can generate incredible
198 volumes of log messages. Among the most prolific offenders
199 are <parameter>relay</parameter> which spits out a log
200 message every time a win32 function is called,
201 <parameter>win</parameter> which tracks windows message
202 passing, and of course <parameter>all</parameter> which is
203 an alias for every single debug channel that exists. For a
204 complex application, your debug logs can easily top 1 MB and
205 higher. A <parameter>relay</parameter> trace can often
206 generate more than 10 MB of log messages, depending on how
207 long you run the application. (As described in the
208 <link linkend = "config-debug-etc">Debug</link>
209 section of configuring wine you can
210 modify what the <parameter>relay</parameter> trace reports).
211 Logging does slow down Wine
212 quite a bit, so don't use <parameter>--debugmsg</parameter>
213 unless you really do want log files.
216 Within each debug channel, you can further specify a
217 <firstterm>message class</firstterm>, to filter out the
218 different severities of errors. The four message classes
220 <simplelist type="inline">
221 <member><parameter>trace</parameter></member>
222 <member><parameter>fixme</parameter></member>
223 <member><parameter>warn</parameter></member>
224 <member><parameter>err</parameter></member>
228 To turn on a debug channel, use the form
229 <parameter>class+channel</parameter>. To turn it off, use
230 <parameter>class-channel</parameter>. To list more than one
231 channel in the same <parameter>--debugmsg</parameter>
232 option, separate them with commas. For example, to request
233 <parameter>warn</parameter> class messages in the
234 <parameter>heap</parameter> debug channel, you could invoke
235 <command>wine</command> like this:
238 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
241 If you leave off the message class, <command>wine</command>
242 will display messages from all four classes for that channel:
245 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
248 If you wanted to see log messages for everything except the
249 relay channel, you might do something like this:
252 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
255 Here is a list of the debug channels and classes in Wine.
256 More channels will be added to (or subtracted from) later
260 <table frame="none"><title>Debug Channels</title>
261 <tgroup cols=5 align="left">
264 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
266 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
268 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
270 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
272 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
274 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
276 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
278 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
280 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
282 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
284 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
286 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
288 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
290 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
292 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
294 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
296 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
298 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
300 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
302 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
304 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
306 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
308 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
310 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
312 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
314 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
316 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
318 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
320 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
322 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
324 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
326 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
328 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
330 winspool</><entry>wnet</><entry>x11</>
337 For more details about debug channels, check out the
338 <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
339 The Wine Developer's Guide</ulink>.
346 Specifies whether to load the builtin or the native (if
347 available) version of a DLL.
350 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
352 See the <link linkend="config-dll">DLL chapter</link> for more details.
357 <title>--help</title>
359 Shows a small command line help page.
364 <title>--version</title>
366 Shows the Wine version string. Useful to verify your installation.
371 <sect1 id="wineserver-command-line-options">
372 <title>wineserver Command Line Options</title>
375 wineserver usually gets started automatically by Wine whenever
376 the first wine process gets started.
377 However, wineserver has some useful command line options that
378 you can add if you start it up manually, e.g. via a user login
382 <sect2 id="wineserver-config-parameter">
383 <title>-d<n></title>
385 Sets the debug level for debug output in the terminal that
386 wineserver got started in at level <n>.
387 In other words: everything greater than 0 will enable
388 wineserver specific debugging output (not to confuse with Wine's wineserver logging channel, --debugmsg +server, though!).
395 Display wineserver command line options help message.
402 Kill the current wineserver, optionally with signal n.
409 This parameter makes wineserver persistent, optionally for n
410 seconds. It will prevent wineserver from shutting down immediately.
413 Usually, wineserver quits almost immediately after the last
414 wine process using this wineserver terminated.
415 However, since wineserver loads a lot of things on startup
416 (such as the whole Windows registry data), its startup might
417 be so slow that it's very useful to keep it from exiting after
418 the end of all Wine sessions, by making it persistent.
425 This parameter makes a newly started wineserver wait until the
426 currently active wineserver instance terminates.
431 <sect1 id="environment-variables">
432 <title>Setting Windows/DOS environment variables</title>
434 Your program might require some environment variable to be set
435 properly in order to run successfully.
436 In this case you need to set this environment variable in the
437 Linux shell, since Wine will pass on the entire shell environment
438 variable settings to the Windows environment variable space.
439 Example for the bash shell (other shells may have a different syntax
442 export MYENVIRONMENTVAR=myenvironmentvarsetting
444 This will make sure your Windows program can access the
445 MYENVIRONMENTVAR environment variable once you start your program
447 If you want to have MYENVIRONMENTVAR set permanently, then you can
448 place the setting into /etc/profile, or also ~/.bashrc in the case of
452 Note however that there is an exception to the rule:
453 If you want to change the PATH environment variable, then of
454 course you can't modify it that way, since this will alter the
455 Unix PATH environment setting. Instead, you should set the
456 WINEPATH environment variable. An alternative way to
457 indicate the content of the DOS PATH environment variable would
458 be to change the "path" setting in the wine config file's <link
459 linkend="config-wine">[wine]</link> section.
464 <sect1 id="CUI-programs">
465 <title>Text mode programs (CUI: Console User Interface)</title>
466 <para>Text mode programs are program which output is only made
467 out of text (surprise!). In Windows terminology, they are
468 called CUI (Console User Interface) executables, by opposition
469 to GUI (Graphical User Interface) executables. Win32 API
470 provide a complete set of APIs to handle this situation, which
471 goes from basic features like text printing, up to high level
472 functionalities (like full screen editing, color support,
473 cursor motion, mouse support), going through features like
474 line editing or raw/cooked input stream support
477 Given the wide scope of features above, and the current usage
478 in Un*x world, Wine comes out with three different ways for
479 running a console program (aka a CUI executable):
488 wineconsole with user backend
493 wineconsole with curses backend
498 <para>The names here are a bit obscure. "bare streams" means
499 that no extra support of wine is provide to map between the
500 unix console access and Windows console access. The two other
501 ways require the use of a specific Wine program (wineconsole)
502 which provide extended facilities. The following table
503 describes what you can do (and cannot do) with those three
506 <title>Basic differences in consoles</title>
507 <tgroup cols="4" align="left">
510 <entry>Function</entry>
511 <entry>Bare streams</entry>
512 <entry>Wineconsole & user backend</entry>
513 <entry>Wineconsole & curses backend</entry>
518 <entry>How to run (assuming executable is called foo.exe)</entry>
520 <screen><prompt>$</prompt> <userinput>wine foo.exe</userinput></screen>
523 <screen><prompt>$</prompt> <userinput>wineconsole -- --backend=user foo.exe</userinput></screen>
526 <screen><prompt>$</prompt> <userinput>wineconsole foo.exe</userinput></screen>
527 </msgtext>You can also use --backend=curses as an option</entry>
530 <entry>Good support for line oriented CUI applications
531 (which print information line after line)
538 <entry>Good support for full screen CUI
539 applications (including but not limited to color
540 support, mouse support...)</entry>
546 <entry>Can be run even if X11 is not running</entry>
552 <entry>Implementation</entry>
553 <entry>Maps the standard Windows streams to the
554 standard Unix streams (stdin/stdout/stderr)
557 Wineconsole will create a new Window (hence
558 requiring the USER32 DLL is available) where all
559 information will be displayed
562 Wineconsole will use existing unix console
563 (from which the program is run) and with the help of
564 the (n)curses library take control of all the terminal
565 surface for interacting with the user
569 <entry>Known limitations</entry>
573 Will produce strange behavior if two (or more)
574 Windows consoles are used on the same Un*x terminal.
581 <sect2 id="CUI-programs-config">
582 <title>Configuration of CUI executables</title>
584 When wineconsole is used, several configuration options are
585 available. Wine (as Windows do) stores, on a per application
586 basis, several options in the registry. This let a user, for
587 example, define the default screen-buffer size he would like
588 to have for a given application.
591 As of today, only the USER backend allows you to edit those
592 options (we don't recommend editing by hand the registry
593 contents). This edition is fired when a user right click in
594 the console (this popups a menu), where you can either
599 Default: this will edit the settings shared by all
600 applications which haven't been configured yet. So,
601 when an application is first run (on your machine,
602 under your account) in wineconsole, wineconsole will
603 inherit this default settings for the
604 application. Afterwards, the application will have its
605 own settings, that you'll be able to modify at your will.
608 Properties: this will edit the application's
609 settings. When you're done, with the edition, you'll
610 be prompted whether you want to:
614 Keep these modified settings only for this
615 session (next time you run the application, you
616 will not see the modification you've just made).
621 Use the settings for this session and save them
622 as well, so that next you run your application,
623 you'll use these new settings again.
632 Here's the list of the items you can configure, and their
635 <title>Wineconsole configuration options</title>
636 <tgroup cols="2" align="left">
639 <entry>Configuration option</entry>
640 <entry>Meaning</entry>
645 <entry>Cursor's size</entry>
647 Defines the size of the cursor. Three options are
648 available: small (33% of character height), medium
649 (66%) and large (100%)
653 <entry>Popup menu</entry>
655 It's been said earlier that wineconsole
656 configuration popup was triggered using a right
657 click in the console's window. However, this can
658 be an issue when the application you run inside
659 wineconsole expects the right click events to be
660 sent to it. By ticking control or shift you select
661 additional modifiers on the right click for
662 opening the popup. For example, ticking shift will
663 send events to the application when you right
664 click the window without shift being hold down,
665 and open the window when you right-click while
666 shift being hold down.
670 <entry>Quick edit</entry>
672 This tick box lets you decide whether left-click
673 mouse events shall be interpreted as events to be
674 sent to the underlying application (tick off) or
675 as a selection of rectangular part of the screen
676 to be later on copied onto the clipboard (tick on).
680 <entry>History</entry>
682 This lets you pick up how many commands you want
683 the console to recall. You can also drive whether
684 you want, when entering several times the same
685 command - potentially intertwined with others -
686 whether you want to store all of them (tick off)
687 or only the last one (tick on).
691 <entry>Police</entry>
693 The Police property sheet allows you to pick the
694 default font for the console (font file, size,
695 background and foreground color).
699 <entry>Screenbuffer & window size</entry>
701 The console as you see it is made of two different
702 parts. On one hand there's the screenbuffer which
703 contains all the information your application puts
704 on the screen, and the window which displays a
705 given area of this screen buffer. Note that the
706 window is always smaller or of the same size than
707 the screen buffer. Having a stricly smaller window
708 size will put on scrollbars on the window so that
709 you can see the whole screenbuffer's content.
713 <entry>Close on exit</entry>
715 If it's ticked, then the wineconsole will exit
716 when the application within terminates. Otherwise,
717 it'll remain opened until the user manually closes
718 it: this allows seeing the latest information of a
719 program after it has terminated.
723 <entry>Edition mode</entry>
727 When the user enter commands, he or she can
728 choose between several edition modes:
732 Emacs: the same keybindings as under
733 emacs are available. For example, Ctrl-A
734 will bring the cursor to the beginning
735 of the edition line. See your emacs
736 manual for the details of the commands.
741 Win32: this are the standard Windows
742 console key-bindings (mainly using
759 <!-- Keep this comment at the end of the file
762 sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")
projects / wine / blob