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>
11 <sect1 id="basic-usage">
12 <title>Basic usage: applications and control panel applets</title>
14 Assuming you are using a fake windows installation, you install
15 applications into Wine in the same way you would in Windows:
16 by running the installer. You can just accept the defaults
17 for where to install, most installers will default to "C:\Program Files",
18 which is fine. If the application installer requests it, you may find that
19 Wine creates icons on your desktop and in your app menu. If that happens, you
20 can start the app by clicking on them.
24 The standard way to uninstall things is for the application to provide an
25 uninstaller, usually registered with the "Add/Remove Programs" control panel
26 applet. Unfortunately as of the time of writing, Wine doesn't provide an
27 Add/Remove control panel applet, so you'll have to run the uninstall manually, either
28 from the menu or from the command line.
32 Some programs install associated control panel applets, examples of this would be
33 Internet Explorer and QuickTime. You can access the Wine control panel by running:
37 <prompt>$</prompt> <userinput>wine control</userinput>
41 which will open a window with the installed control panel applets in it, as in Windows.
45 If the application doesn't install menu or desktop items, you'll need to run the app
46 from the command line. Remembering where you installed to, something like:
50 <prompt>$</prompt> <userinput>wine "c:\program files\appname\appname.exe"</userinput>
54 will probably do the trick. The path isn't case sensitive, but remember to include the double quotes.
55 Some programs don't always use obvious naming for their directories and EXE files, so you might have
56 to look inside the program files directory to see what it put where
60 <sect1 id="running-wine">
61 <title>How to run Wine</title>
63 Wine is a very complicated piece of software with many ways to
64 adjust how it runs. With very few exceptions, you can
65 activate the same set of features through the <link
66 linkend="configuring">configuration file </link> as you can
67 with command-line parameters. In this chapter, we'll briefly
68 discuss these parameters, and match them up with their
69 corresponding configuration variables.
73 You can invoke the <command>wine --help</command> command to
74 get a listing of all Wine's command-line parameters:
78 Usage: ./wine [options] program_name [arguments]
81 --debugmsg name Turn debugging-messages on or off
82 --dll name Enable or disable built-in DLLs
83 --help,-h Show this help message
84 --version,-v Display the Wine version
89 You can specify as many options as you want, if any.
90 Typically, you will want to have your configuration file set
91 up with a sensible set of defaults; in this case, you can run
92 <command>wine</command> without explicitly listing any
93 options. In rare cases, you might want to override certain
94 parameters on the command line.
97 After the options, you should put the name of the file you
98 want <command>wine</command> to execute. If the executable is
99 in the <parameter>Path</parameter> parameter in the
100 configuration file, you can simply give the executable file
101 name. However, if the executable is not in
102 <parameter>Path</parameter>, you must give the full path to
103 the executable (in Windows format, not UNIX format!). For
104 example, given a <parameter>Path</parameter> of the following:
108 "Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"
111 You could run the file
112 <filename>c:\windows\system\foo.exe</filename> with:
115 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
118 However, you would have to run the file
119 <filename>c:\myapps\foo.exe</filename> with this command:
122 <prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
125 (note the backslash-escaped "\" !)
128 For details on running text mode (CUI) executables, read the
129 <link linkend="CUI-programs">section</link> below.
133 <sect1 id="command-line-options">
134 <title>Command-Line Options</title>
136 <sect2 id="config-parameter">
137 <title>--debugmsg [channels]</title>
139 Wine isn't perfect, and many Windows applications still
140 don't run without bugs under Wine (but then, a lot of programs
141 don't run without bugs under native Windows either!). To
142 make it easier for people to track down the causes behind
143 each bug, Wine provides a number of <firstterm>debug
144 channels</firstterm> that you can tap into.
147 Each debug channel, when activated, will trigger logging
148 messages to be displayed to the console where you invoked
149 <command>wine</command>. From there you can redirect the
150 messages to a file and examine it at your leisure. But be
151 forewarned! Some debug channels can generate incredible
152 volumes of log messages. Among the most prolific offenders
153 are <parameter>relay</parameter> which spits out a log
154 message every time a win32 function is called,
155 <parameter>win</parameter> which tracks windows message
156 passing, and of course <parameter>all</parameter> which is
157 an alias for every single debug channel that exists. For a
158 complex application, your debug logs can easily top 1 MB and
159 higher. A <parameter>relay</parameter> trace can often
160 generate more than 10 MB of log messages, depending on how
161 long you run the application. (As described in the
162 <link linkend = "config-debug-etc">Debug</link>
163 section of configuring wine you can
164 modify what the <parameter>relay</parameter> trace reports).
165 Logging does slow down Wine
166 quite a bit, so don't use <parameter>--debugmsg</parameter>
167 unless you really do want log files.
170 Within each debug channel, you can further specify a
171 <firstterm>message class</firstterm>, to filter out the
172 different severities of errors. The four message classes
174 <simplelist type="inline">
175 <member><parameter>trace</parameter></member>
176 <member><parameter>fixme</parameter></member>
177 <member><parameter>warn</parameter></member>
178 <member><parameter>err</parameter></member>
182 To turn on a debug channel, use the form
183 <parameter>class+channel</parameter>. To turn it off, use
184 <parameter>class-channel</parameter>. To list more than one
185 channel in the same <parameter>--debugmsg</parameter>
186 option, separate them with commas. For example, to request
187 <parameter>warn</parameter> class messages in the
188 <parameter>heap</parameter> debug channel, you could invoke
189 <command>wine</command> like this:
192 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
195 If you leave off the message class, <command>wine</command>
196 will display messages from all four classes for that channel:
199 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
202 If you wanted to see log messages for everything except the
203 relay channel, you might do something like this:
206 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
209 Here is a master list of all the debug channels and classes
210 in Wine. More channels will be added to (or subtracted
211 from) later versions.
214 <table frame="none"><title>Debug Channels</title>
215 <tgroup cols=5 align="left">
218 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
220 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
222 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
224 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
226 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
228 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
230 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
232 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
234 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
236 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
238 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
240 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
242 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
244 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
246 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
248 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
250 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
252 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
254 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
256 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
258 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
260 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
262 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
264 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
266 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
268 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
270 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
272 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
274 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
276 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
278 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
280 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
282 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
284 winspool</><entry>wnet</><entry>x11</>
291 For more details about debug channels, check out the
292 <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
293 The Wine Developer's Guide</ulink>.
300 Specifies whether to load the builtin or the native (if
301 available) version of a DLL.
304 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
306 See the <link linkend="dll-config">DLL chapter</link> for more details.
311 <title>--help</title>
313 Shows a small command line help page.
318 <title>--version</title>
320 Shows the Wine version string. Useful to verify your installation.
325 <sect1 id="environment-variables">
326 <title>Setting Windows/DOS environment variables</title>
328 Your program might require some environment variable to be set
329 properly in order to run successfully.
330 In this case you need to set this environment variable in the
331 Linux shell, since Wine will pass on the entire shell environment
332 variable settings to the Windows environment variable space.
333 Example for the bash shell (other shells may have a different syntax
336 export MYENVIRONMENTVAR=myenvironmentvarsetting
338 This will make sure your Windows program can access the
339 MYENVIRONMENTVAR environment variable once you start your program
341 If you want to have MYENVIRONMENTVAR set permanently, then you can
342 place the setting into /etc/profile, or also ~/.bashrc in the case of
346 Note however that there is an exception to the rule:
347 If you want to change the PATH environment variable, then of
348 course you can't modify it that way, since this will alter the
349 Unix PATH environment setting. Instead, you should set the
350 WINEPATH environment variable. An alternative way to
351 indicate the content of the DOS PATH environment variable would
352 be to change the "path" setting in the wine config file's <link
353 linkend="config-wine">[wine]</link> section.
358 <sect1 id="CUI-programs">
359 <title>Text mode programs (CUI: Console User Interface)</title>
360 <para>Text mode programs are program which output is only made
361 out of text (surprise!). In Windows terminolgy, they are
362 called CUI (Console User Interface) executables, by opposition
363 to GUI (Graphical User Interface) executables. Win32 API
364 provide a complete set of APIs to handle this situation, which
365 goes from basic features like text printing, up to high level
366 functionnalities (like full screen editing, color support,
367 cursor motion, mouse support), going through features like
368 line editing or raw/cooked input stream support
371 Given the wide scope of features above, and the current usage
372 in Un*x world, Wine comes out with three different ways for
373 running a console program (aka a CUI executable):
376 <para>bare streams</para>
379 <para>wineconsole with user backend</para>
382 <para>wineconsole with curses backend</para>
386 <para>The names here are a bit obscure. "bare streams" means
387 that no extra support of wine is provide to map between the
388 unix console access and Windows console access. The two other
389 ways require the use of a specific Wine program (wineconsole)
390 which provide extended facilities. The following table
391 describes what you can do (and cannot do) with those three
394 <title>Basic differences in consoles</title>
395 <tgroup cols="4" align="left">
398 <entry>Function</entry>
399 <entry>Bare streams</entry>
400 <entry>Wineconsole & user backend</entry>
401 <entry>Wineconsole & curses backend</entry>
406 <entry>How to run (assuming executable is called foo.exe)</entry>
408 <screen><prompt>$</prompt> <userinput>wine foo.exe</userinput></screen>
411 <screen><prompt>$</prompt> <userinput>wineconsole -- --backend=user foo.exe</userinput></screen>
414 <screen><prompt>$</prompt> <userinput>wineconsole foo.exe</userinput></screen>
415 </msgtext>You can also use --backend=curses as an option</entry>
418 <entry>Good support for line oriented CUI applications
419 (which print information line after line)
426 <entry>Good support for full screen CUI
427 applications (including but not limited to color
428 support, mouse support...)</entry>
434 <entry>Can be run even if X11 is not running</entry>
440 <entry>Implementation</entry>
441 <entry>Maps the standard Windows streams to the
442 standard Unix streams (stdin/stdout/stderr)
445 Wineconsole will create a new Window (hence
446 requiring the USER32 DLL is available) where all
447 information will be displayed
450 Wineconsole will use existing unix console
451 (from which the program is run) and with the help of
452 the (n)curses library take control of all the terminal
453 surface for interacting with the user
457 <entry>Known limitations</entry>
461 Will produce strange behavior if two (or more)
462 Windows consoles are used on the same Un*x terminal.
469 <sect2 id="CUI-programs-config">
470 <title>Configuration of CUI executables</title>
472 When wineconsole is used, several configuration options are
473 available. Wine (as Windows do) stores, on a per application
474 basis, several options in the registry. This let a user, for
475 example, define the default screen-buffer size he would like
476 to have for a given application.
479 As of today, only the USER backend allows you to edit those
480 options (we don't recommend editing by hand the registry
481 contents). This edition is fired when a user right click in
482 the console (this popups a menu), where you can either
487 Default: this will edit the settings shared by all
488 applications which haven't been configured yet. So,
489 when an application is first run (on your machine,
490 under your account) in wineconsole, wineconsole will
491 inherit this default settings for the
492 application. Afterwards, the application will have its
493 own settings, that you'll be able to modify at your will.
496 Properties: this will edit the application's
497 settings. When you're done, with the edition, you'll
498 be prompted whether you want to:
502 Keep these modified settings only for this
503 session (next time you run the application, you
504 will not see the modification you've just made).
509 Use the settings for this session and save them
510 as well, so that next you run your application,
511 you'll use these new settings again.
520 Here's the list of the items you can configure, and their
523 <title>Wineconsole configuration options</title>
524 <tgroup cols="2" align="left">
527 <entry>Configuration option</entry>
528 <entry>Meaning</entry>
533 <entry>Cursor's size</entry>
535 Defines the size of the cursor. Three options are
536 available: small (33% of character height), medium
537 (66%) and large (100%)
541 <entry>Popup menu</entry>
543 It's been said earlier that wineconsole
544 configuration popup was triggered using a right
545 click in the console's window. However, this can
546 be an issue when the application you run inside
547 wineconsole expects the right click events to be
548 sent to it. By ticking control or shift you select
549 additional modifiers on the right click for
550 opening the popup. For example, ticking shift will
551 send events to the application when you right
552 click the window without shift being hold down,
553 and open the window when you right-click while
554 shift being hold down.
558 <entry>Quick edit</entry>
560 This tick box lets you decide whether left-click
561 mouse events shall be interpreted as events to be
562 sent to the underlying application (tick off) or
563 as a selection of rectangular part of the screen
564 to be later on copied onto the clipboard (tick on).
568 <entry>History</entry>
570 This lets you pick up how many commands you want
571 the console to recall. You can also drive whether
572 you want, when entering several times the same
573 command - potentially intertwened with others -
574 whether you want to store all of them (tick off)
575 or only the last one (tick on).
579 <entry>Police</entry>
581 The Police property sheet allows you to pick the
582 default font for the console (font file, size,
583 background and foreground color).
587 <entry>Screenbuffer & window size</entry>
589 The console as you see it is made of two different
590 parts. On one hand there's the screenbuffer which
591 contains all the information your application puts
592 on the screen, and the window which displays a
593 given area of this screen buffer. Note that the
594 window is always smaller or of the same size than
595 the screen buffer. Having a stricly smaller window
596 size will put on scrollbars on the window so that
597 you can see the whole screenbuffer's content.
601 <entry>Close on exit</entry>
603 If it's ticked, then the wineconsole will exit
604 when the application within terminates. Otherwise,
605 it'll remain opened until the user manually closes
606 it: this allows seeing the latest information of a
607 program after it has terminated.
611 <entry>Edition mode</entry>
615 When the user enter commands, he or she can
616 choose between several edition modes:
620 Emacs: the same keybindings as under
621 emacs are available. For example, Ctrl-A
622 will bring the cursor to the beginning
623 of the edition line. See your emacs
624 manual for the details of the commands.
629 Win32: this are the standard Windows
630 console key-bindings (mainly using
647 <!-- Keep this comment at the end of the file
650 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
projects / wine / blob