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    --dll name       Enable or disable built-in DLLs
  31    --dosver x.xx    DOS version to imitate (e.g. 6.22)
  32                     Only valid with --winver win31
  33    --help,-h        Show this help message
  34    --managed        Allow the window manager to manage created windows
  35    --version,-v     Display the Wine version
  36    --winver         Version to imitate
  37                     (win95,nt40,win31,nt2k,win98,nt351,win30,win20)
  38         </screen>
  39       </para>
  40
  41       <para>
  42         You can specify as many options as you want, if any.
  43         Typically, you will want to have your configuration file set
  44         up with a sensible set of defaults; in this case, you can run
  45         <command>wine</command> without explicitly listing any
  46         options.  In rare cases, you might want to override certain
  47         parameters on the command line.
  48       </para>
  49       <para>
  50         After the options, you should put the name of the file you
  51         want <command>wine</command> to execute.  If the executable is
  52         in the <parameter>Path</parameter> parameter in the
  53         configuration file, you can simply give the executable file
  54         name.  However, if the executable is not in
  55         <parameter>Path</parameter>, you must give the full path to
  56         the executable (in Windows format, not UNIX format!).  For
  57         example, given a <parameter>Path</parameter> of the following:
  58       </para>
  59       <screen>
  60 [wine]
  61 "Path"="c:\windows;c:\windows\system;e:\;e:\test;f:\"
  62       </screen>
  63       <para>
  64         You could run the file
  65         <filename>c:\windows\system\foo.exe</filename> with:
  66       </para>
  67       <screen>
  68 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
  69       </screen>
  70       <para>
  71         However, you would have to run the file
  72         <filename>c:\myapps\foo.exe</filename> with this command:
  73       </para>
  74       <screen>
  75 <prompt>$</prompt> <userinput>wine c:\myapps\foo.exe</userinput>
  76       </screen>
  77       <para>
  78         Finally, if you want to pass any parameters to your windows
  79         application, you can list them at the end, just after the
  80         executable name.  Thus, to run the imaginary
  81         <command>foo.exe</command> Windows application with its
  82         <parameter>/advanced</parameter> mode parameter, while
  83         invoking Wine in <link
  84         linkend="managed-parameter"><parameter>--managed</parameter>
  85         mode</link>, you would do something like this:
  86       </para>
  87       <screen>
  88 <prompt>$</prompt> <userinput>wine --managed foo.exe /advanced</userinput>
  89       </screen>
  90       <para>
  91         In other words, options that affect Wine should come
  92         <emphasis>before</emphasis> the Windows program name, while
  93         options that affect the Windows program should come
  94         <emphasis>after</emphasis> it.
  95       </para>
  96     </sect1>
  97
  98     <sect1 id="command-line-options">
  99       <title>Command-Line Options</title>
 100
 101       <sect2 id="config-parameter">
 102         <title>--debugmsg [channels]</title>
 103         <para>
 104           Wine isn't perfect, and many Windows applications still
 105           don't run without bugs under Wine (but then, many of them
 106           don't run without bugs under native Windows either!).  To
 107           make it easier for people to track down the causes behind
 108           each bug, Wine provides a number of <firstterm>debug
 109           channels</firstterm> that you can tap into.
 110         </para>
 111         <para>
 112           Each debug channel, when activated, will trigger logging
 113           messages to be displayed to the console where you invoked
 114           <command>wine</command>.  From there you can redirect the
 115           messages to a file and examine it at your leisure.  But be
 116           forewarned!  Some debug channels can generate incredible
 117           volumes of log messages.  Among the most prolific offenders
 118           are <parameter>relay</parameter> which spits out a log
 119           message every time a win32 function is called,
 120           <parameter>win</parameter> which tracks windows message
 121           passing, and of course <parameter>all</parameter> which is
 122           an alias for every single debug channel that exists.  For a
 123           complex application, your debug logs can easily top 1 MB and
 124           higher.  A <parameter>relay</parameter> trace can often
 125           generate more than 10 MB of log messages, depending on how
 126           long you run the application.  Logging does slow down Wine
 127           quite a bit, so don't use <parameter>--debugmsg</parameter>
 128           unless you really do want log files.
 129         </para>
 130         <para>
 131           Within each debug channel, you can further specify a
 132           <firstterm>message class</firstterm>, to filter out the
 133           different severities of errors.  The four message classes
 134           are:
 135           <simplelist type="inline">
 136             <member><parameter>trace</parameter></member>
 137             <member><parameter>fixme</parameter></member>
 138             <member><parameter>warn</parameter></member>
 139             <member><parameter>err</parameter></member>
 140           </simplelist>.
 141         </para>
 142         <para>
 143           To turn on a debug channel, use the form
 144           <parameter>class+channel</parameter>.  To turn it off, use
 145           <parameter>class-channel</parameter>.  To list more than one
 146           channel in the same <parameter>--debugmsg</parameter>
 147           option, separate them with commas.  For example, to request
 148           <parameter>warn</parameter> class messages in the
 149           <parameter>heap</parameter> debug channel, you could invoke
 150           <command>wine</command> like this:
 151         </para>
 152         <screen>
 153 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
 154         </screen>
 155         <para>
 156           If you leave off the message class, <command>wine</command>
 157           will display messages from all four classes for that channel:
 158         </para>
 159         <screen>
 160 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
 161         </screen>
 162         <para>
 163           If you wanted to see log messages for everything except the
 164           relay channel, you might do something like this:
 165         </para>
 166         <screen>
 167 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
 168         </screen>
 169         <para>
 170           Here is a master list of all the debug channels and classes
 171           in Wine.  More channels might be added to (or subtracted
 172           from) later versions.
 173         </para>
 174
 175                 <table frame="none"><title>Debug Channels</title>
 176                 <tgroup cols=5 align="left">
 177                 <tbody>
 178 <row><entry>
 179 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
 180 </row><row><entry>
 181 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
 182 </row><row><entry>
 183 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
 184 </row><row><entry>
 185 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
 186 </row><row><entry>
 187 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
 188 </row><row><entry>
 189 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
 190 </row><row><entry>
 191 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
 192 </row><row><entry>
 193 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
 194 </row><row><entry>
 195 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
 196 </row><row><entry>
 197 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
 198 </row><row><entry>
 199 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
 200 </row><row><entry>
 201 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
 202 </row><row><entry>
 203 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
 204 </row><row><entry>
 205 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>ldt</>
 206 </row><row><entry>
 207 listbox</><entry> listview</><entry> local</><entry>mci</><entry>mcianim</>
 208 </row><row><entry>
 209 mciavi</><entry>mcicda</><entry> mcimidi</><entry> mciwave</><entry> mdi</>
 210 </row><row><entry>
 211 menu</><entry> message</><entry> metafile</><entry>midi</><entry> mmaux</>
 212 </row><row><entry>
 213 mmio</><entry> mmsys</><entry> mmtime</><entry> module</><entry>monthcal</>
 214 </row><row><entry>
 215 mpr</><entry> msacm</><entry> msg</><entry> msvideo</><entry> nativefont</>
 216 </row><row><entry>
 217 nonclient</><entry> ntdll</><entry> odbc</><entry> ole</><entry> opengl</>
 218 </row><row><entry>
 219 pager</><entry> palette</><entry> pidl</><entry> print</><entry> process</>
 220 </row><row><entry>
 221 profile</><entry> progress</><entry>prop</><entry> propsheet</><entry>psapi</>
 222 </row><row><entry>
 223 psdrv</><entry> ras</><entry> rebar</><entry> reg</><entry> region</>
 224 </row><row><entry>
 225 relay</><entry> resource</><entry>richedit</><entry>scroll</><entry>segment</>
 226 </row><row><entry>
 227 seh</><entry>selector</><entry>sendmsg</><entry> server</><entry>setupapi</>
 228 </row><row><entry>
 229 setupx</><entry>shell</><entry> snoop</><entry> sound</><entry>static</>
 230 </row><row><entry>
 231 statusbar</><entry>storage</><entry> stress</><entry> string</><entry>syscolor</>
 232 </row><row><entry>
 233 system</><entry> tab</><entry>tape</><entry>tapi</><entry>task</>
 234 </row><row><entry>
 235 text</><entry>thread</><entry>thunk</><entry>timer</><entry> toolbar</>
 236 </row><row><entry>
 237 toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</><entry>ttydrv</>
 238 </row><row><entry>
 239 tweak</><entry>typelib</><entry> updown</><entry>ver</><entry>virtual</>
 240 </row><row><entry>
 241 vxd</><entry>wave</><entry>win</><entry>win16drv</><entry>win32</>
 242 </row><row><entry>
 243 wing</><entry>wininet</><entry> winsock</><entry> winspool</><entry>wnet</>
 244 </row><row><entry>
 245 x11</><entry> x11drv</>
 246 </row>
 247                 </tbody>
 248                 </tgroup>
 249                 </table>
 250
 251         <para>
 252           For more details about debug channels, check out the
 253           <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
 254             The Wine Developer's Guide</ulink>.
 255         </para>
 256       </sect2>
 257
 258       <sect2>
 259         <title>--dll</title>
 260         <para>
 261
 262         </para>
 263       </sect2>
 264
 265       <sect2>
 266         <title>--dosver</title>
 267         <para>
 268
 269         </para>
 270       </sect2>
 271
 272       <sect2>
 273         <title>--help</title>
 274         <para>
 275
 276         </para>
 277       </sect2>
 278
 279       <sect2 id="managed-parameter">
 280         <title>--managed</title>
 281         <para>
 282
 283         </para>
 284       </sect2>
 285
 286       <sect2>
 287         <title>--version</title>
 288         <para>
 289
 290         </para>
 291       </sect2>
 292
 293       <sect2>
 294         <title>--winver</title>
 295         <para>
 296
 297         </para>
 298       </sect2>
 299     </sect1>
 300   </chapter>
 301
 302 <!-- Keep this comment at the end of the file
 303 Local variables:
 304 mode: sgml
 305 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 306 End:
 307 -->