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