2 <title>Running Wine</title>
5 This chapter will describe all aspects of running Wine, like e.g.
6 basic Wine invocation, command line parameters of various Wine
11 This chapter will describe all aspects of running Wine, like e.g.
12 basic Wine invocation, command line parameters of various Wine
20 <sect1 id="basic-usage">
21 <title>Basic usage: applications and control panel applets</title>
23 Assuming you are using a fake Windows installation, you install
24 applications into Wine in the same way you would in Windows: by
25 running the installer. You can just accept the defaults for
26 where to install, most installers will default to "C:\Program
27 Files", which is fine. If the application installer requests it,
28 you may find that Wine creates icons on your desktop and in your
29 app menu. If that happens, you can start the app by clicking on
34 The standard way to uninstall things is for the application to
35 provide an uninstaller, usually registered with the "Add/Remove
36 Programs" control panel applet.
37 To access the Wine equivalent, run the <command>uninstaller</command>
38 program (it is located in the
39 <filename>programs/uninstaller/</filename> directory in a Wine
40 source directory) in a <glossterm>terminal</glossterm>:
44 <prompt>$</prompt> <userinput>uninstaller</userinput>
48 Some programs install associated control panel applets, examples
49 of this would be Internet Explorer and QuickTime. You can access
50 the Wine control panel by running in a
51 <glossterm>terminal</glossterm>:
55 <prompt>$</prompt> <userinput>wine control</userinput>
59 which will open a window with the installed control panel
60 applets in it, as in Windows.
64 If the application doesn't install menu or desktop items, you'll
65 need to run the app from the command line. Remembering where you
66 installed to, something like:
70 <prompt>$</prompt> <userinput>wine "c:\program files\appname\appname.exe"</userinput>
74 will probably do the trick. The path isn't case sensitive, but
75 remember to include the double quotes. Some programs don't
76 always use obvious naming for their directories and EXE files,
77 so you might have to look inside the program files directory to
78 see what it put where.
82 <sect1 id="running-wine">
83 <title>How to run Wine</title>
85 Wine is a very complicated piece of software with many ways to
86 adjust how it runs. With very few exceptions, you can
87 activate the same set of features through the <link
88 linkend="config-file">configuration file</link> as you can
89 with command-line parameters. In this chapter, we'll briefly
90 discuss these parameters, and match them up with their
91 corresponding configuration variables.
95 You can invoke the <command>wine --help</command> command to
96 get a listing of all Wine's command-line parameters:
100 Usage: ./wine [options] program_name [arguments]
103 --debugmsg name Turn debugging-messages on or off
104 --dll name Enable or disable built-in DLLs
105 --help,-h Show this help message
106 --version,-v Display the Wine version
111 You can specify as many options as you want, if any.
112 Typically, you will want to have your configuration file set
113 up with a sensible set of defaults; in this case, you can run
114 <command>wine</command> without explicitly listing any
115 options. In rare cases, you might want to override certain
116 parameters on the command line.
119 After the options, you should put the name of the file you
120 want <command>wine</command> to execute. If the executable is
121 in the <parameter>Path</parameter> parameter in the
122 configuration file, you can simply give the executable file
123 name. However, if the executable is not in
124 <parameter>Path</parameter>, you must give the full path to
125 the executable (in Windows format, not UNIX format!). For
126 example, given a <parameter>Path</parameter> of the following:
130 "Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"
133 You could run the file
134 <filename>c:\windows\system\foo.exe</filename> with:
137 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
140 However, you would have to run the file
141 <filename>c:\myapps\foo.exe</filename> with this command:
144 <prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
147 (note the backslash-escaped "\" !)
150 For details on running text mode (CUI) executables, read the
151 <link linkend="CUI-programs">section</link> below.
155 <sect1 id="explorer-like-wine">
156 <title>Explorer-like graphical Wine environments</title>
159 If you don't feel like manually invoking Wine for every program
160 you want to run and instead want to have an integrated graphical
161 interface to run your Windows programs in, then installing e.g.
162 <ulink url="http://www.calmira.org">Calmira</ulink>, a
163 Win95-Explorer-like shell replacement, would probably be a great
164 idea. Calmira might still have a few problems running on Wine,
165 though. Other usable Explorer replacements should be listed here
170 <sect1 id="command-line-options">
171 <title>Wine Command Line Options</title>
173 <sect2 id="config-parameter">
174 <title>--debugmsg [channels]</title>
176 Wine isn't perfect, and many Windows applications still
177 don't run without bugs under Wine (but then, a lot of programs
178 don't run without bugs under native Windows either!). To
179 make it easier for people to track down the causes behind
180 each bug, Wine provides a number of <firstterm>debug
181 channels</firstterm> that you can tap into.
184 Each debug channel, when activated, will trigger logging
185 messages to be displayed to the console where you invoked
186 <command>wine</command>. From there you can redirect the
187 messages to a file and examine it at your leisure. But be
188 forewarned! Some debug channels can generate incredible
189 volumes of log messages. Among the most prolific offenders
190 are <parameter>relay</parameter> which spits out a log
191 message every time a win32 function is called,
192 <parameter>win</parameter> which tracks windows message
193 passing, and of course <parameter>all</parameter> which is
194 an alias for every single debug channel that exists. For a
195 complex application, your debug logs can easily top 1 MB and
196 higher. A <parameter>relay</parameter> trace can often
197 generate more than 10 MB of log messages, depending on how
198 long you run the application. (As described in the
199 <link linkend = "config-debug-etc">Debug</link>
200 section of configuring wine you can
201 modify what the <parameter>relay</parameter> trace reports).
202 Logging does slow down Wine
203 quite a bit, so don't use <parameter>--debugmsg</parameter>
204 unless you really do want log files.
207 Within each debug channel, you can further specify a
208 <firstterm>message class</firstterm>, to filter out the
209 different severities of errors. The four message classes
211 <simplelist type="inline">
212 <member><parameter>trace</parameter></member>
213 <member><parameter>fixme</parameter></member>
214 <member><parameter>warn</parameter></member>
215 <member><parameter>err</parameter></member>
219 To turn on a debug channel, use the form
220 <parameter>class+channel</parameter>. To turn it off, use
221 <parameter>class-channel</parameter>. To list more than one
222 channel in the same <parameter>--debugmsg</parameter>
223 option, separate them with commas. For example, to request
224 <parameter>warn</parameter> class messages in the
225 <parameter>heap</parameter> debug channel, you could invoke
226 <command>wine</command> like this:
229 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
232 If you leave off the message class, <command>wine</command>
233 will display messages from all four classes for that channel:
236 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
239 If you wanted to see log messages for everything except the
240 relay channel, you might do something like this:
243 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
246 Here is a list of the debug channels and classes in Wine.
247 More channels will be added to (or subtracted from) later
251 <table frame="none"><title>Debug Channels</title>
252 <tgroup cols=5 align="left">
255 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
257 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
259 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
261 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
263 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
265 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
267 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
269 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
271 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
273 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
275 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
277 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
279 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
281 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
283 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
285 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
287 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
289 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
291 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
293 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
295 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
297 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
299 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
301 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
303 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
305 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
307 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
309 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
311 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
313 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
315 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
317 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
319 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
321 winspool</><entry>wnet</><entry>x11</>
328 For more details about debug channels, check out the
329 <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
330 The Wine Developer's Guide</ulink>.
337 Specifies whether to load the builtin or the native (if
338 available) version of a DLL.
341 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
343 See the <link linkend="config-dll">DLL chapter</link> for more details.
348 <title>--help</title>
350 Shows a small command line help page.
355 <title>--version</title>
357 Shows the Wine version string. Useful to verify your installation.
362 <sect1 id="wineserver-command-line-options">
363 <title>wineserver Command Line Options</title>
366 wineserver usually gets started automatically by Wine whenever
367 the first wine process gets started.
368 However, wineserver has some useful command line options that
369 you can add if you start it up manually, e.g. via a user login
373 <sect2 id="wineserver-config-parameter">
374 <title>-d<n></title>
376 Sets the debug level for debug output in the terminal that
377 wineserver got started in at level <n>.
378 In other words: everything greater than 0 will enable
379 wineserver specific debugging output (not to confuse with Wine's wineserver logging channel, --debugmsg +server, though!).
386 Display wineserver command line options help message.
393 Kill the current wineserver, optionally with signal n.
400 This parameter makes wineserver persistent, optionally for n
401 seconds. It will prevent wineserver from shutting down immediately.
404 Usually, wineserver quits almost immediately after the last
405 wine process using this wineserver terminated.
406 However, since wineserver loads a lot of things on startup
407 (such as the whole Windows registry data), its startup might
408 be so slow that it's very useful to keep it from exiting after
409 the end of all Wine sessions, by making it persistent.
416 This parameter makes a newly started wineserver wait until the
417 currently active wineserver instance terminates.
422 <sect1 id="environment-variables">
423 <title>Setting Windows/DOS environment variables</title>
425 Your program might require some environment variable to be set
426 properly in order to run successfully.
427 In this case you need to set this environment variable in the
428 Linux shell, since Wine will pass on the entire shell environment
429 variable settings to the Windows environment variable space.
430 Example for the bash shell (other shells may have a different syntax
433 export MYENVIRONMENTVAR=myenvironmentvarsetting
435 This will make sure your Windows program can access the
436 MYENVIRONMENTVAR environment variable once you start your program
438 If you want to have MYENVIRONMENTVAR set permanently, then you can
439 place the setting into /etc/profile, or also ~/.bashrc in the case of
443 Note however that there is an exception to the rule:
444 If you want to change the PATH environment variable, then of
445 course you can't modify it that way, since this will alter the
446 Unix PATH environment setting. Instead, you should set the
447 WINEPATH environment variable. An alternative way to
448 indicate the content of the DOS PATH environment variable would
449 be to change the "path" setting in the wine config file's <link
450 linkend="config-wine">[wine]</link> section.
455 <sect1 id="CUI-programs">
456 <title>Text mode programs (CUI: Console User Interface)</title>
457 <para>Text mode programs are program which output is only made
458 out of text (surprise!). In Windows terminology, they are
459 called CUI (Console User Interface) executables, by opposition
460 to GUI (Graphical User Interface) executables. Win32 API
461 provide a complete set of APIs to handle this situation, which
462 goes from basic features like text printing, up to high level
463 functionalities (like full screen editing, color support,
464 cursor motion, mouse support), going through features like
465 line editing or raw/cooked input stream support
468 Given the wide scope of features above, and the current usage
469 in Un*x world, Wine comes out with three different ways for
470 running a console program (aka a CUI executable):
479 wineconsole with user backend
484 wineconsole with curses backend
489 <para>The names here are a bit obscure. "bare streams" means
490 that no extra support of wine is provide to map between the
491 unix console access and Windows console access. The two other
492 ways require the use of a specific Wine program (wineconsole)
493 which provide extended facilities. The following table
494 describes what you can do (and cannot do) with those three
497 <title>Basic differences in consoles</title>
498 <tgroup cols="4" align="left">
501 <entry>Function</entry>
502 <entry>Bare streams</entry>
503 <entry>Wineconsole & user backend</entry>
504 <entry>Wineconsole & curses backend</entry>
509 <entry>How to run (assuming executable is called foo.exe)</entry>
511 <screen><prompt>$</prompt> <userinput>wine foo.exe</userinput></screen>
514 <screen><prompt>$</prompt> <userinput>wineconsole -- --backend=user foo.exe</userinput></screen>
517 <screen><prompt>$</prompt> <userinput>wineconsole foo.exe</userinput></screen>
518 </msgtext>You can also use --backend=curses as an option</entry>
521 <entry>Good support for line oriented CUI applications
522 (which print information line after line)
529 <entry>Good support for full screen CUI
530 applications (including but not limited to color
531 support, mouse support...)</entry>
537 <entry>Can be run even if X11 is not running</entry>
543 <entry>Implementation</entry>
544 <entry>Maps the standard Windows streams to the
545 standard Unix streams (stdin/stdout/stderr)
548 Wineconsole will create a new Window (hence
549 requiring the USER32 DLL is available) where all
550 information will be displayed
553 Wineconsole will use existing unix console
554 (from which the program is run) and with the help of
555 the (n)curses library take control of all the terminal
556 surface for interacting with the user
560 <entry>Known limitations</entry>
564 Will produce strange behavior if two (or more)
565 Windows consoles are used on the same Un*x terminal.
572 <sect2 id="CUI-programs-config">
573 <title>Configuration of CUI executables</title>
575 When wineconsole is used, several configuration options are
576 available. Wine (as Windows do) stores, on a per application
577 basis, several options in the registry. This let a user, for
578 example, define the default screen-buffer size he would like
579 to have for a given application.
582 As of today, only the USER backend allows you to edit those
583 options (we don't recommend editing by hand the registry
584 contents). This edition is fired when a user right click in
585 the console (this popups a menu), where you can either
590 Default: this will edit the settings shared by all
591 applications which haven't been configured yet. So,
592 when an application is first run (on your machine,
593 under your account) in wineconsole, wineconsole will
594 inherit this default settings for the
595 application. Afterwards, the application will have its
596 own settings, that you'll be able to modify at your will.
599 Properties: this will edit the application's
600 settings. When you're done, with the edition, you'll
601 be prompted whether you want to:
605 Keep these modified settings only for this
606 session (next time you run the application, you
607 will not see the modification you've just made).
612 Use the settings for this session and save them
613 as well, so that next you run your application,
614 you'll use these new settings again.
623 Here's the list of the items you can configure, and their
626 <title>Wineconsole configuration options</title>
627 <tgroup cols="2" align="left">
630 <entry>Configuration option</entry>
631 <entry>Meaning</entry>
636 <entry>Cursor's size</entry>
638 Defines the size of the cursor. Three options are
639 available: small (33% of character height), medium
640 (66%) and large (100%)
644 <entry>Popup menu</entry>
646 It's been said earlier that wineconsole
647 configuration popup was triggered using a right
648 click in the console's window. However, this can
649 be an issue when the application you run inside
650 wineconsole expects the right click events to be
651 sent to it. By ticking control or shift you select
652 additional modifiers on the right click for
653 opening the popup. For example, ticking shift will
654 send events to the application when you right
655 click the window without shift being hold down,
656 and open the window when you right-click while
657 shift being hold down.
661 <entry>Quick edit</entry>
663 This tick box lets you decide whether left-click
664 mouse events shall be interpreted as events to be
665 sent to the underlying application (tick off) or
666 as a selection of rectangular part of the screen
667 to be later on copied onto the clipboard (tick on).
671 <entry>History</entry>
673 This lets you pick up how many commands you want
674 the console to recall. You can also drive whether
675 you want, when entering several times the same
676 command - potentially intertwined with others -
677 whether you want to store all of them (tick off)
678 or only the last one (tick on).
682 <entry>Police</entry>
684 The Police property sheet allows you to pick the
685 default font for the console (font file, size,
686 background and foreground color).
690 <entry>Screenbuffer & window size</entry>
692 The console as you see it is made of two different
693 parts. On one hand there's the screenbuffer which
694 contains all the information your application puts
695 on the screen, and the window which displays a
696 given area of this screen buffer. Note that the
697 window is always smaller or of the same size than
698 the screen buffer. Having a stricly smaller window
699 size will put on scrollbars on the window so that
700 you can see the whole screenbuffer's content.
704 <entry>Close on exit</entry>
706 If it's ticked, then the wineconsole will exit
707 when the application within terminates. Otherwise,
708 it'll remain opened until the user manually closes
709 it: this allows seeing the latest information of a
710 program after it has terminated.
714 <entry>Edition mode</entry>
718 When the user enter commands, he or she can
719 choose between several edition modes:
723 Emacs: the same keybindings as under
724 emacs are available. For example, Ctrl-A
725 will bring the cursor to the beginning
726 of the edition line. See your emacs
727 manual for the details of the commands.
732 Win32: this are the standard Windows
733 console key-bindings (mainly using
750 <!-- Keep this comment at the end of the file
753 sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")
projects / wine / blob