Removed uses of u_long. Use void* type for pointers where possible.
[wine/wine-kai.git] / documentation / running.sgml
blob83c267def33b623fdc6ffdfdbacc88e0f02adbe7
1 <chapter id="running">
2 <title>Running Wine</title>
4 <para>
5 Written by &name-john-sheets; <email>&email-john-sheets;</email>
6 </para>
7 <para>
8 Extended by &name-mike-hearn; <email>&email-mike-hearn;</email>, &name-eric-pouech; <email>&email-eric-pouech;</email>
9 </para>
11 <sect1 id="basic-usage">
12 <title>Basic usage: applications and control panel applets</title>
13 <para>
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.
21 </para>
23 <para>
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. To access the Wine equivalent, run the "uninstaller" program:
27 </para>
29 <screen>
30 <prompt>$</prompt> <userinput>uninstaller</userinput>
31 </screen>
33 <para>
34 Some programs install associated control panel applets, examples of this would be
35 Internet Explorer and QuickTime. You can access the Wine control panel by running:
36 </para>
38 <screen>
39 <prompt>$</prompt> <userinput>wine control</userinput>
40 </screen>
42 <para>
43 which will open a window with the installed control panel applets in it, as in Windows.
44 </para>
46 <para>
47 If the application doesn't install menu or desktop items, you'll need to run the app
48 from the command line. Remembering where you installed to, something like:
49 </para>
51 <screen>
52 <prompt>$</prompt> <userinput>wine "c:\program files\appname\appname.exe"</userinput>
53 </screen>
55 <para>
56 will probably do the trick. The path isn't case sensitive, but remember to include the double quotes.
57 Some programs don't always use obvious naming for their directories and EXE files, so you might have
58 to look inside the program files directory to see what it put where
59 </para>
60 </sect1>
62 <sect1 id="running-wine">
63 <title>How to run Wine</title>
64 <para>
65 Wine is a very complicated piece of software with many ways to
66 adjust how it runs. With very few exceptions, you can
67 activate the same set of features through the <link
68 linkend="configuring">configuration file </link> as you can
69 with command-line parameters. In this chapter, we'll briefly
70 discuss these parameters, and match them up with their
71 corresponding configuration variables.
72 </para>
74 <para>
75 You can invoke the <command>wine --help</command> command to
76 get a listing of all Wine's command-line parameters:
77 </para>
78 <para>
79 <screen>
80 Usage: ./wine [options] program_name [arguments]
82 Options:
83 --debugmsg name Turn debugging-messages on or off
84 --dll name Enable or disable built-in DLLs
85 --help,-h Show this help message
86 --version,-v Display the Wine version
87 </screen>
88 </para>
90 <para>
91 You can specify as many options as you want, if any.
92 Typically, you will want to have your configuration file set
93 up with a sensible set of defaults; in this case, you can run
94 <command>wine</command> without explicitly listing any
95 options. In rare cases, you might want to override certain
96 parameters on the command line.
97 </para>
98 <para>
99 After the options, you should put the name of the file you
100 want <command>wine</command> to execute. If the executable is
101 in the <parameter>Path</parameter> parameter in the
102 configuration file, you can simply give the executable file
103 name. However, if the executable is not in
104 <parameter>Path</parameter>, you must give the full path to
105 the executable (in Windows format, not UNIX format!). For
106 example, given a <parameter>Path</parameter> of the following:
107 </para>
108 <screen>
109 [wine]
110 "Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"
111 </screen>
112 <para>
113 You could run the file
114 <filename>c:\windows\system\foo.exe</filename> with:
115 </para>
116 <screen>
117 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
118 </screen>
119 <para>
120 However, you would have to run the file
121 <filename>c:\myapps\foo.exe</filename> with this command:
122 </para>
123 <screen>
124 <prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
125 </screen>
126 <para>
127 (note the backslash-escaped "\" !)
128 </para>
129 <para>
130 For details on running text mode (CUI) executables, read the
131 <link linkend="CUI-programs">section</link> below.
132 </para>
133 </sect1>
135 <sect1 id="command-line-options">
136 <title>Command-Line Options</title>
138 <sect2 id="config-parameter">
139 <title>--debugmsg [channels]</title>
140 <para>
141 Wine isn't perfect, and many Windows applications still
142 don't run without bugs under Wine (but then, a lot of programs
143 don't run without bugs under native Windows either!). To
144 make it easier for people to track down the causes behind
145 each bug, Wine provides a number of <firstterm>debug
146 channels</firstterm> that you can tap into.
147 </para>
148 <para>
149 Each debug channel, when activated, will trigger logging
150 messages to be displayed to the console where you invoked
151 <command>wine</command>. From there you can redirect the
152 messages to a file and examine it at your leisure. But be
153 forewarned! Some debug channels can generate incredible
154 volumes of log messages. Among the most prolific offenders
155 are <parameter>relay</parameter> which spits out a log
156 message every time a win32 function is called,
157 <parameter>win</parameter> which tracks windows message
158 passing, and of course <parameter>all</parameter> which is
159 an alias for every single debug channel that exists. For a
160 complex application, your debug logs can easily top 1 MB and
161 higher. A <parameter>relay</parameter> trace can often
162 generate more than 10 MB of log messages, depending on how
163 long you run the application. (As described in the
164 <link linkend = "config-debug-etc">Debug</link>
165 section of configuring wine you can
166 modify what the <parameter>relay</parameter> trace reports).
167 Logging does slow down Wine
168 quite a bit, so don't use <parameter>--debugmsg</parameter>
169 unless you really do want log files.
170 </para>
171 <para>
172 Within each debug channel, you can further specify a
173 <firstterm>message class</firstterm>, to filter out the
174 different severities of errors. The four message classes
175 are:
176 <simplelist type="inline">
177 <member><parameter>trace</parameter></member>
178 <member><parameter>fixme</parameter></member>
179 <member><parameter>warn</parameter></member>
180 <member><parameter>err</parameter></member>
181 </simplelist>.
182 </para>
183 <para>
184 To turn on a debug channel, use the form
185 <parameter>class+channel</parameter>. To turn it off, use
186 <parameter>class-channel</parameter>. To list more than one
187 channel in the same <parameter>--debugmsg</parameter>
188 option, separate them with commas. For example, to request
189 <parameter>warn</parameter> class messages in the
190 <parameter>heap</parameter> debug channel, you could invoke
191 <command>wine</command> like this:
192 </para>
193 <screen>
194 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
195 </screen>
196 <para>
197 If you leave off the message class, <command>wine</command>
198 will display messages from all four classes for that channel:
199 </para>
200 <screen>
201 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
202 </screen>
203 <para>
204 If you wanted to see log messages for everything except the
205 relay channel, you might do something like this:
206 </para>
207 <screen>
208 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
209 </screen>
210 <para>
211 Here is a master list of all the debug channels and classes
212 in Wine. More channels will be added to (or subtracted
213 from) later versions.
214 </para>
216 <table frame="none"><title>Debug Channels</title>
217 <tgroup cols=5 align="left">
218 <tbody>
219 <row><entry>
220 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
221 </row><row><entry>
222 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
223 </row><row><entry>
224 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
225 </row><row><entry>
226 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
227 </row><row><entry>
228 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
229 </row><row><entry>
230 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
231 </row><row><entry>
232 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
233 </row><row><entry>
234 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
235 </row><row><entry>
236 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
237 </row><row><entry>
238 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
239 </row><row><entry>
240 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
241 </row><row><entry>
242 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
243 </row><row><entry>
244 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
245 </row><row><entry>
246 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
247 </row><row><entry>
248 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
249 </row><row><entry>
250 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
251 </row><row><entry>
252 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
253 </row><row><entry>
254 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
255 </row><row><entry>
256 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
257 </row><row><entry>
258 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
259 </row><row><entry>
260 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
261 </row><row><entry>
262 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
263 </row><row><entry>
264 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
265 </row><row><entry>
266 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
267 </row><row><entry>
268 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
269 </row><row><entry>
270 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
271 </row><row><entry>
272 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
273 </row><row><entry>
274 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
275 </row><row><entry>
276 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
277 </row><row><entry>
278 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
279 </row><row><entry>
280 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
281 </row><row><entry>
282 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
283 </row><row><entry>
284 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
285 </row><row><entry>
286 winspool</><entry>wnet</><entry>x11</>
287 </row>
288 </tbody>
289 </tgroup>
290 </table>
292 <para>
293 For more details about debug channels, check out the
294 <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
295 The Wine Developer's Guide</ulink>.
296 </para>
297 </sect2>
299 <sect2>
300 <title>--dll</title>
301 <para>
302 Specifies whether to load the builtin or the native (if
303 available) version of a DLL.
304 Example:
305 <screen>
306 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
307 </screen>
308 See the <link linkend="dll-config">DLL chapter</link> for more details.
309 </para>
310 </sect2>
312 <sect2>
313 <title>--help</title>
314 <para>
315 Shows a small command line help page.
316 </para>
317 </sect2>
319 <sect2>
320 <title>--version</title>
321 <para>
322 Shows the Wine version string. Useful to verify your installation.
323 </para>
324 </sect2>
325 </sect1>
327 <sect1 id="environment-variables">
328 <title>Setting Windows/DOS environment variables</title>
329 <para>
330 Your program might require some environment variable to be set
331 properly in order to run successfully.
332 In this case you need to set this environment variable in the
333 Linux shell, since Wine will pass on the entire shell environment
334 variable settings to the Windows environment variable space.
335 Example for the bash shell (other shells may have a different syntax
337 <screen>
338 export MYENVIRONMENTVAR=myenvironmentvarsetting
339 </screen>
340 This will make sure your Windows program can access the
341 MYENVIRONMENTVAR environment variable once you start your program
342 using Wine.
343 If you want to have MYENVIRONMENTVAR set permanently, then you can
344 place the setting into /etc/profile, or also ~/.bashrc in the case of
345 bash.
346 </para>
347 <para>
348 Note however that there is an exception to the rule:
349 If you want to change the PATH environment variable, then of
350 course you can't modify it that way, since this will alter the
351 Unix PATH environment setting. Instead, you should set the
352 WINEPATH environment variable. An alternative way to
353 indicate the content of the DOS PATH environment variable would
354 be to change the "path" setting in the wine config file's <link
355 linkend="config-wine">[wine]</link> section.
356 </para>
358 </sect1>
360 <sect1 id="CUI-programs">
361 <title>Text mode programs (CUI: Console User Interface)</title>
362 <para>Text mode programs are program which output is only made
363 out of text (surprise!). In Windows terminolgy, they are
364 called CUI (Console User Interface) executables, by opposition
365 to GUI (Graphical User Interface) executables. Win32 API
366 provide a complete set of APIs to handle this situation, which
367 goes from basic features like text printing, up to high level
368 functionnalities (like full screen editing, color support,
369 cursor motion, mouse support), going through features like
370 line editing or raw/cooked input stream support
371 </para>
372 <para>
373 Given the wide scope of features above, and the current usage
374 in Un*x world, Wine comes out with three different ways for
375 running a console program (aka a CUI executable):
376 <itemizedlist>
377 <listitem>
378 <para>bare streams</para>
379 </listitem>
380 <listitem>
381 <para>wineconsole with user backend</para>
382 </listitem>
383 <listitem>
384 <para>wineconsole with curses backend</para>
385 </listitem>
386 </itemizedlist>
387 </para>
388 <para>The names here are a bit obscure. "bare streams" means
389 that no extra support of wine is provide to map between the
390 unix console access and Windows console access. The two other
391 ways require the use of a specific Wine program (wineconsole)
392 which provide extended facilities. The following table
393 describes what you can do (and cannot do) with those three
394 ways.
395 <table>
396 <title>Basic differences in consoles</title>
397 <tgroup cols="4" align="left">
398 <thead>
399 <row>
400 <entry>Function</entry>
401 <entry>Bare streams</entry>
402 <entry>Wineconsole &amp; user backend</entry>
403 <entry>Wineconsole &amp; curses backend</entry>
404 </row>
405 </thead>
406 <tbody>
407 <row>
408 <entry>How to run (assuming executable is called foo.exe)</entry>
409 <entry><msgtext>
410 <screen><prompt>$</prompt> <userinput>wine foo.exe</userinput></screen>
411 </msgtext></entry>
412 <entry><msgtext>
413 <screen><prompt>$</prompt> <userinput>wineconsole -- --backend=user foo.exe</userinput></screen>
414 </msgtext></entry>
415 <entry><msgtext>
416 <screen><prompt>$</prompt> <userinput>wineconsole foo.exe</userinput></screen>
417 </msgtext>You can also use --backend=curses as an option</entry>
418 </row>
419 <row>
420 <entry>Good support for line oriented CUI applications
421 (which print information line after line)
422 </entry>
423 <entry>Yes</entry>
424 <entry>Yes</entry>
425 <entry>Yes</entry>
426 </row>
427 <row>
428 <entry>Good support for full screen CUI
429 applications (including but not limited to color
430 support, mouse support...)</entry>
431 <entry>No</entry>
432 <entry>Yes</entry>
433 <entry>Yes</entry>
434 </row>
435 <row>
436 <entry>Can be run even if X11 is not running</entry>
437 <entry>Yes</entry>
438 <entry>No</entry>
439 <entry>Yes</entry>
440 </row>
441 <row>
442 <entry>Implementation</entry>
443 <entry>Maps the standard Windows streams to the
444 standard Unix streams (stdin/stdout/stderr)
445 </entry>
446 <entry>
447 Wineconsole will create a new Window (hence
448 requiring the USER32 DLL is available) where all
449 information will be displayed
450 </entry>
451 <entry>
452 Wineconsole will use existing unix console
453 (from which the program is run) and with the help of
454 the (n)curses library take control of all the terminal
455 surface for interacting with the user
456 </entry>
457 </row>
458 <row>
459 <entry>Known limitations</entry>
460 <entry></entry>
461 <entry></entry>
462 <entry>
463 Will produce strange behavior if two (or more)
464 Windows consoles are used on the same Un*x terminal.
465 </entry>
466 </row>
467 </tbody>
468 </tgroup>
469 </table>
470 </para>
471 <sect2 id="CUI-programs-config">
472 <title>Configuration of CUI executables</title>
473 <para>
474 When wineconsole is used, several configuration options are
475 available. Wine (as Windows do) stores, on a per application
476 basis, several options in the registry. This let a user, for
477 example, define the default screen-buffer size he would like
478 to have for a given application.
479 </para>
480 <para>
481 As of today, only the USER backend allows you to edit those
482 options (we don't recommend editing by hand the registry
483 contents). This edition is fired when a user right click in
484 the console (this popups a menu), where you can either
485 choose from:
486 <itemizedlist>
487 <listitem>
488 <para>
489 Default: this will edit the settings shared by all
490 applications which haven't been configured yet. So,
491 when an application is first run (on your machine,
492 under your account) in wineconsole, wineconsole will
493 inherit this default settings for the
494 application. Afterwards, the application will have its
495 own settings, that you'll be able to modify at your will.
496 </para>
497 <para>
498 Properties: this will edit the application's
499 settings. When you're done, with the edition, you'll
500 be prompted whether you want to:
501 <orderedlist>
502 <listitem>
503 <para>
504 Keep these modified settings only for this
505 session (next time you run the application, you
506 will not see the modification you've just made).
507 </para>
508 </listitem>
509 <listitem>
510 <para>
511 Use the settings for this session and save them
512 as well, so that next you run your application,
513 you'll use these new settings again.
514 </para>
515 </listitem>
516 </orderedlist>
517 </para>
518 </listitem>
519 </itemizedlist>
520 </para>
521 <para>
522 Here's the list of the items you can configure, and their
523 meanings:
524 <table>
525 <title>Wineconsole configuration options</title>
526 <tgroup cols="2" align="left">
527 <thead>
528 <row>
529 <entry>Configuration option</entry>
530 <entry>Meaning</entry>
531 </row>
532 </thead>
533 <tbody>
534 <row>
535 <entry>Cursor's size</entry>
536 <entry>
537 Defines the size of the cursor. Three options are
538 available: small (33% of character height), medium
539 (66%) and large (100%)
540 </entry>
541 </row>
542 <row>
543 <entry>Popup menu</entry>
544 <entry>
545 It's been said earlier that wineconsole
546 configuration popup was triggered using a right
547 click in the console's window. However, this can
548 be an issue when the application you run inside
549 wineconsole expects the right click events to be
550 sent to it. By ticking control or shift you select
551 additional modifiers on the right click for
552 opening the popup. For example, ticking shift will
553 send events to the application when you right
554 click the window without shift being hold down,
555 and open the window when you right-click while
556 shift being hold down.
557 </entry>
558 </row>
559 <row>
560 <entry>Quick edit</entry>
561 <entry>
562 This tick box lets you decide whether left-click
563 mouse events shall be interpreted as events to be
564 sent to the underlying application (tick off) or
565 as a selection of rectangular part of the screen
566 to be later on copied onto the clipboard (tick on).
567 </entry>
568 </row>
569 <row>
570 <entry>History</entry>
571 <entry>
572 This lets you pick up how many commands you want
573 the console to recall. You can also drive whether
574 you want, when entering several times the same
575 command - potentially intertwened with others -
576 whether you want to store all of them (tick off)
577 or only the last one (tick on).
578 </entry>
579 </row>
580 <row>
581 <entry>Police</entry>
582 <entry>
583 The Police property sheet allows you to pick the
584 default font for the console (font file, size,
585 background and foreground color).
586 </entry>
587 </row>
588 <row>
589 <entry>Screenbuffer &amp; window size</entry>
590 <entry>
591 The console as you see it is made of two different
592 parts. On one hand there's the screenbuffer which
593 contains all the information your application puts
594 on the screen, and the window which displays a
595 given area of this screen buffer. Note that the
596 window is always smaller or of the same size than
597 the screen buffer. Having a stricly smaller window
598 size will put on scrollbars on the window so that
599 you can see the whole screenbuffer's content.
600 </entry>
601 </row>
602 <row>
603 <entry>Close on exit</entry>
604 <entry>
605 If it's ticked, then the wineconsole will exit
606 when the application within terminates. Otherwise,
607 it'll remain opened until the user manually closes
608 it: this allows seeing the latest information of a
609 program after it has terminated.
610 </entry>
611 </row>
612 <row>
613 <entry>Edition mode</entry>
614 <entry>
615 <msgtext>
616 <para>
617 When the user enter commands, he or she can
618 choose between several edition modes:
619 <itemizedlist>
620 <listitem>
621 <para>
622 Emacs: the same keybindings as under
623 emacs are available. For example, Ctrl-A
624 will bring the cursor to the beginning
625 of the edition line. See your emacs
626 manual for the details of the commands.
627 </para>
628 </listitem>
629 <listitem>
630 <para>
631 Win32: this are the standard Windows
632 console key-bindings (mainly using
633 arrows).
634 </para>
635 </listitem>
636 </itemizedlist>
637 </para>
638 </msgtext>
639 </entry>
640 </row>
641 </tbody>
642 </tgroup>
643 </table>
644 </para>
645 </sect2>
646 </sect1>
647 </chapter>
649 <!-- Keep this comment at the end of the file
650 Local variables:
651 mode: sgml
652 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
653 End: