documentation/running.sgml

   1   <chapter id="running">
   2     <title>Running Wine</title>
   3
   4     <para>
   5       Written by &name-john-sheets; <email>&email-john-sheets;</email>
   6     </para>
   7
   8     <sect1 id="running-wine">
   9       <title>How to run Wine</title>
  10       <para>
  11         Wine is a very complicated piece of software with many ways to
  12         adjust how it runs.  With very few exceptions, you can
  13         activate the same set of features through the <link
  14         linkend="configuring">configuration file </link> as you can
  15         with command-line parameters.  In this chapter, we'll briefly
  16         discuss these parameters, and match them up with their
  17         corresponding configuration variables.
  18       </para>
  19
  20       <para>
  21         You can invoke the <command>wine --help</command> command to
  22         get a listing of all Wine's command-line parameters:
  23       </para>
  24       <para>
  25         <screen>
  26 Usage: ./wine [options] program_name [arguments]
  27
  28 Options:
  29    --debugmsg name  Turn debugging-messages on or off
  30    --desktop geom   Use a desktop window of the given geometry
  31    --display name   Use the specified display
  32    --dll name       Enable or disable built-in DLLs
  33    --dosver x.xx    DOS version to imitate (e.g. 6.22)
  34                     Only valid with --winver win31
  35    --help,-h        Show this help message
  36    --language xx    Set the language (one of Br,Ca,Cs,Cy,Da,De,En,Eo,Es,Fi,Fr,Ga,Gd,Gv,
  37                     Hr,Hu,It,Ja,Ko,Kw,Nl,No,Pl,Pt,Sk,Sv,Ru,Wa)
  38    --managed        Allow the window manager to manage created windows
  39    --synchronous    Turn on synchronous display mode
  40    --version,-v     Display the Wine version
  41    --winver         Version to imitate (win95,nt40,win31,nt2k,win98,nt351,win30,win20)
  42         </screen>
  43       </para>
  44
  45       <para>
  46         You can specify as many options as you want, if any.
  47         Typically, you will want to have your configuration file set
  48         up with a sensible set of defaults; in this case, you can run
  49         <command>wine</command> without explicitly listing any
  50         options.  In rare cases, you might want to override certain
  51         parameters on the command line.
  52       </para>
  53       <para>
  54         After the options, you should put the name of the file you
  55         want <command>wine</command> to execute.  If the executable is
  56         in the <parameter>Path</parameter> parameter in the
  57         configuration file, you can simply give the executable file
  58         name.  However, if the executable is not in
  59         <parameter>Path</parameter>, you must give the full path to
  60         the executable (in Windows format, not UNIX format!).  For
  61         example, given a <parameter>Path</parameter> of the following:
  62       </para>
  63       <screen>
  64 [wine]
  65 "Path"="c:\windows;c:\windows\system;e:\;e:\test;f:\"
  66       </screen>
  67       <para>
  68         You could run the file
  69         <filename>c:\windows\system\foo.exe</filename> with:
  70       </para>
  71       <screen>
  72 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
  73       </screen>
  74       <para>
  75         However, you would have to run the file
  76         <filename>c:\myapps\foo.exe</filename> with this command:
  77       </para>
  78       <screen>
  79 <prompt>$</prompt> <userinput>wine c:\myapps\foo.exe</userinput>
  80       </screen>
  81       <para>
  82         Finally, if you want to pass any parameters to your windows
  83         application, you can list them at the end, just after the
  84         executable name.  Thus, to run the imaginary
  85         <command>foo.exe</command> Windows application with its
  86         <parameter>/advanced</parameter> mode parameter, while
  87         invoking Wine in <link
  88         linkend="managed-parameter"><parameter>--managed</parameter>
  89         mode</link>, you would do something like this:
  90       </para>
  91       <screen>
  92 <prompt>$</prompt> <userinput>wine --managed foo.exe /advanced</userinput>
  93       </screen>
  94       <para>
  95         In other words, options that affect Wine should come
  96         <emphasis>before</emphasis> the Windows program name, while
  97         options that affect the Windows program should come
  98         <emphasis>after</emphasis> it.
  99       </para>
 100     </sect1>
 101
 102     <sect1 id="command-line-options">
 103       <title>Command-Line Options</title>
 104
 105       <sect2 id="config-parameter">
 106         <title>--debugmsg [channels]</title>
 107         <para>
 108           Wine isn't perfect, and many Windows applications still
 109           don't run without bugs under Wine (but then, many of them
 110           don't run without bugs under native Windows either!).  To
 111           make it easier for people to track down the causes behind
 112           each bug, Wine provides a number of <firstterm>debug
 113           channels</firstterm> that you can tap into.
 114         </para>
 115         <para>
 116           Each debug channel, when activated, will trigger logging
 117           messages to be displayed to the console where you invoked
 118           <command>wine</command>.  From there you can redirect the
 119           messages to a file and examine it at your leisure.  But be
 120           forewarned!  Some debug channels can generate incredible
 121           volumes of log messages.  Among the most prolific offenders
 122           are <parameter>relay</parameter> which spits out a log
 123           message every time a win32 function is called,
 124           <parameter>win</parameter> which tracks windows message
 125           passing, and of course <parameter>all</parameter> which is
 126           an alias for every single debug channel that exists.  For a
 127           complex application, your debug logs can easily top 1 MB and
 128           higher.  A <parameter>relay</parameter> trace can often
 129           generate more than 10 MB of log messages, depending on how
 130           long you run the application.  Logging does slow down Wine
 131           quite a bit, so don't use <parameter>--debugmsg</parameter>
 132           unless you really do want log files.
 133         </para>
 134         <para>
 135           Within each debug channel, you can further specify a
 136           <firstterm>message class</firstterm>, to filter out the
 137           different severities of errors.  The four message classes
 138           are:
 139           <simplelist type="inline">
 140             <member><parameter>trace</parameter></member>
 141             <member><parameter>fixme</parameter></member>
 142             <member><parameter>warn</parameter></member>
 143             <member><parameter>err</parameter></member>
 144           </simplelist>.
 145         </para>
 146         <para>
 147           To turn on a debug channel, use the form
 148           <parameter>class+channel</parameter>.  To turn it off, use
 149           <parameter>class-channel</parameter>.  To list more than one
 150           channel in the same <parameter>--debugmsg</parameter>
 151           option, separate them with commas.  For example, to request
 152           <parameter>warn</parameter> class messages in the
 153           <parameter>heap</parameter> debug channel, you could invoke
 154           <command>wine</command> like this:
 155         </para>
 156         <screen>
 157 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
 158         </screen>
 159         <para>
 160           If you leave off the message class, <command>wine</command>
 161           will display messages from all four classes for that channel:
 162         </para>
 163         <screen>
 164 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
 165         </screen>
 166         <para>
 167           If you wanted to see log messages for everything except the
 168           relay channel, you might do something like this:
 169         </para>
 170         <screen>
 171 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
 172         </screen>
 173         <para>
 174           Here is a master list of all the debug channels and classes
 175           in Wine.  More channels might be added to (or subtracted
 176           from) later versions.
 177         </para>
 178         <screen>
 179 all       accel     advapi    animate   aspi      atom      avifile   bitblt
 180 bitmap    caret     cdrom     class     clipboard clipping  combo     comboex
 181 comm      commctrl  commdlg   console   crtdll    cursor    datetime  dc
 182 ddeml     ddraw     debug     debugstr  delayhlp  dialog    dinput    dll
 183 dosfs     dosmem    dplay     driver    dsound    edit      elfdll    enhmetafile
 184 event     exec      file      fixup     font      gdi       global    graphics
 185 header    heap      hook      hotkey    icmp      icon      imagehlp  imagelist
 186 imm       int       int10     int16     int17     int19     int21     int31
 187 io        ipaddress joystick  key       keyboard  ldt       listbox   listview
 188 local     mci       mcianim   mciavi    mcicda    mcimidi   mciwave   mdi
 189 menu      message   metafile  midi      mmaux     mmio      mmsys     mmtime
 190 module    monthcal  mpr       msacm     msg       msvideo   nativefont nonclient
 191 ntdll     odbc      ole       opengl    pager     palette   pidl      print
 192 process   profile   progress  prop      propsheet psapi     psdrv     ras
 193 rebar     reg       region    relay     resource  richedit  scroll    segment
 194 seh       selector  sendmsg   server    setupapi  setupx    shell     snoop
 195 sound     static    statusbar storage   stress    string    syscolor  system
 196 tab       tape      tapi      task      text      thread    thunk     timer
 197 toolbar   toolhelp  tooltips  trackbar  treeview  ttydrv    tweak     typelib
 198 updown    ver       virtual   vxd       wave      win       win16drv  win32
 199 wing      wininet   winsock   winspool  wnet      x11       x11drv
 200         </screen>
 201         <para>
 202           For more details about debug channels, check out the
 203           <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
 204             The Wine Developer's Guide</ulink>.
 205         </para>
 206       </sect2>
 207
 208       <sect2>
 209         <title>--desktop [geometry]</title>
 210         <para>
 211           By default, <command>wine</command> runs applications on
 212           your regular desktop.  Wine application windows intermingle
 213           with native X11 applications.  Windows overlap each other,
 214           and you can resize them in relation to each other.
 215           Normally, when you minimize Wine windows, they collapse into
 216           a small icon at the lower left corner of your desktop,
 217           circumventing the behavior of your other non-Wine windows.
 218           However, if you're running in <link linkend="managed-parameter">
 219           --managed mode</link>, your Wine applications will minimize
 220           just like your other windows.
 221         </para>
 222         <para>
 223           Sometimes, you may want to restrict Wine windows to a
 224           smaller area of your desktop.  This is what the
 225           <parameter>--desktop</parameter> option controls.  Whenever
 226           you pass this option to <command>wine</command>, it will
 227           create a window of that size and use that as Wine's desktop
 228           instead of borrowing the regular desktop space.  Wine will
 229           then place the application window inside the new desktop
 230           window.  If you minimize the application, it will iconize to
 231           the bottom left corner of its own desktop window.
 232         </para>
 233         <para>
 234           The <parameter>--desktop</parameter> option geometry info in
 235           the standard X11 geometry format, e.g., "640x480" for a
 236           desktop window 640 pixels wide and 480 pixels high.  You can
 237           also in theory specify the coordinates of the upper left
 238           corner of the desktop window, but your window manager may
 239           choose to override that request.  The following invocation
 240           would open a new 640 x 480 desktop window at coordinates
 241           (10, 25):
 242           <screen>
 243 <prompt>$</prompt> <userinput>wine --desktop 640x480+10+25 foo.exe</userinput>
 244           </screen>
 245         </para>
 246         <para>
 247           More commonly, you'll leave off the starting coordinates,
 248           and only use the height and width:
 249           <screen>
 250 <prompt>$</prompt> <userinput>wine --desktop 640x480 foo.exe</userinput>
 251           </screen>
 252         </para>
 253       </sect2>
 254
 255       <sect2>
 256         <title>--display</title>
 257         <para>
 258           By default, wine will display its windows on whichever X
 259           Display you have in the <envar>$DISPLAY</envar> environment
 260           variable.  Often, <envar>$DISPLAY</envar> is set to
 261           <literal>:0</literal>, which sends all windows to the
 262           primary video monitor on the current host machine.
 263         </para>
 264         <para>
 265           To send windows to a different monitor on the same system,
 266           you could change <literal>:0</literal> to a different
 267           number, for example <literal>:1</literal> to send output to
 268           the second monitor.  You can also specify other systems.  If
 269           you were logged into the system <systemitem
 270           class="systemname">alpha</systemitem>, but wanted wine to
 271           run on another system on the network, <systemitem
 272           class="systemname">beta</systemitem>, you might use a
 273           <envar>$DISPLAY</envar> of <literal>beta:0</literal>.
 274         </para>
 275         <para>
 276           You can also declare display values on the wine command
 277           line, using the <parameter>--display</parameter> option.
 278           The last example above might look like this:
 279         </para>
 280         <programlisting>
 281 <prompt>$</prompt> wine --display="beta:0" foo.exe
 282         </programlisting>
 283       </sect2>
 284
 285       <sect2>
 286         <title>--dll</title>
 287         <para>
 288
 289         </para>
 290       </sect2>
 291
 292       <sect2>
 293         <title>--dosver</title>
 294         <para>
 295
 296         </para>
 297       </sect2>
 298
 299       <sect2>
 300         <title>--help</title>
 301         <para>
 302
 303         </para>
 304       </sect2>
 305
 306       <sect2>
 307         <title>--language</title>
 308         <para>
 309
 310         </para>
 311       </sect2>
 312
 313       <sect2 id="managed-parameter">
 314         <title>--managed</title>
 315         <para>
 316
 317         </para>
 318       </sect2>
 319
 320       <sect2>
 321         <title>--synchronous</title>
 322         <para>
 323
 324         </para>
 325       </sect2>
 326
 327       <sect2>
 328         <title>--version</title>
 329         <para>
 330
 331         </para>
 332       </sect2>
 333
 334       <sect2>
 335         <title>--winver</title>
 336         <para>
 337
 338         </para>
 339       </sect2>
 340     </sect1>
 341   </chapter>
 342
 343 <!-- Keep this comment at the end of the file
 344 Local variables:
 345 mode: sgml
 346 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 347 End:
 348 -->