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
  97       <para>
  98         If you want to run a console program (aka a CUI executable), use
  99         <command>wineconsole</command> instead of <command>wine</command>
 100         to start it. It will display the program in a separate Window
 101         (this requires X11 to be run). If you don't, you'll still be able
 102         to run able your program, in the Unix console were you're started
 103         your program, but with very limited capacities (so, your program
 104         might work, but your mileage may vary). This shall be improved
 105         in the future.
 106       </para>
 107     </sect1>
 108
 109     <sect1 id="command-line-options">
 110       <title>Command-Line Options</title>
 111
 112       <sect2 id="config-parameter">
 113         <title>--debugmsg [channels]</title>
 114         <para>
 115           Wine isn't perfect, and many Windows applications still
 116           don't run without bugs under Wine (but then, many of them
 117           don't run without bugs under native Windows either!).  To
 118           make it easier for people to track down the causes behind
 119           each bug, Wine provides a number of <firstterm>debug
 120           channels</firstterm> that you can tap into.
 121         </para>
 122         <para>
 123           Each debug channel, when activated, will trigger logging
 124           messages to be displayed to the console where you invoked
 125           <command>wine</command>.  From there you can redirect the
 126           messages to a file and examine it at your leisure.  But be
 127           forewarned!  Some debug channels can generate incredible
 128           volumes of log messages.  Among the most prolific offenders
 129           are <parameter>relay</parameter> which spits out a log
 130           message every time a win32 function is called,
 131           <parameter>win</parameter> which tracks windows message
 132           passing, and of course <parameter>all</parameter> which is
 133           an alias for every single debug channel that exists.  For a
 134           complex application, your debug logs can easily top 1 MB and
 135           higher.  A <parameter>relay</parameter> trace can often
 136           generate more than 10 MB of log messages, depending on how
 137           long you run the application.  Logging does slow down Wine
 138           quite a bit, so don't use <parameter>--debugmsg</parameter>
 139           unless you really do want log files.
 140         </para>
 141         <para>
 142           Within each debug channel, you can further specify a
 143           <firstterm>message class</firstterm>, to filter out the
 144           different severities of errors.  The four message classes
 145           are:
 146           <simplelist type="inline">
 147             <member><parameter>trace</parameter></member>
 148             <member><parameter>fixme</parameter></member>
 149             <member><parameter>warn</parameter></member>
 150             <member><parameter>err</parameter></member>
 151           </simplelist>.
 152         </para>
 153         <para>
 154           To turn on a debug channel, use the form
 155           <parameter>class+channel</parameter>.  To turn it off, use
 156           <parameter>class-channel</parameter>.  To list more than one
 157           channel in the same <parameter>--debugmsg</parameter>
 158           option, separate them with commas.  For example, to request
 159           <parameter>warn</parameter> class messages in the
 160           <parameter>heap</parameter> debug channel, you could invoke
 161           <command>wine</command> like this:
 162         </para>
 163         <screen>
 164 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
 165         </screen>
 166         <para>
 167           If you leave off the message class, <command>wine</command>
 168           will display messages from all four classes for that channel:
 169         </para>
 170         <screen>
 171 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
 172         </screen>
 173         <para>
 174           If you wanted to see log messages for everything except the
 175           relay channel, you might do something like this:
 176         </para>
 177         <screen>
 178 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
 179         </screen>
 180         <para>
 181           Here is a master list of all the debug channels and classes
 182           in Wine.  More channels might be added to (or subtracted
 183           from) later versions.
 184         </para>
 185
 186                 <table frame="none"><title>Debug Channels</title>
 187                 <tgroup cols=5 align="left">
 188                 <tbody>
 189 <row><entry>
 190 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
 191 </row><row><entry>
 192 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
 193 </row><row><entry>
 194 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
 195 </row><row><entry>
 196 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
 197 </row><row><entry>
 198 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
 199 </row><row><entry>
 200 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
 201 </row><row><entry>
 202 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
 203 </row><row><entry>
 204 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
 205 </row><row><entry>
 206 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
 207 </row><row><entry>
 208 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
 209 </row><row><entry>
 210 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
 211 </row><row><entry>
 212 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
 213 </row><row><entry>
 214 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
 215 </row><row><entry>
 216 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>ldt</>
 217 </row><row><entry>
 218 listbox</><entry> listview</><entry> local</><entry>mci</><entry>mcianim</>
 219 </row><row><entry>
 220 mciavi</><entry>mcicda</><entry> mcimidi</><entry> mciwave</><entry> mdi</>
 221 </row><row><entry>
 222 menu</><entry> message</><entry> metafile</><entry>midi</><entry> mmaux</>
 223 </row><row><entry>
 224 mmio</><entry> mmsys</><entry> mmtime</><entry> module</><entry>monthcal</>
 225 </row><row><entry>
 226 mpr</><entry> msacm</><entry> msg</><entry> msvideo</><entry> nativefont</>
 227 </row><row><entry>
 228 nonclient</><entry> ntdll</><entry> odbc</><entry> ole</><entry> opengl</>
 229 </row><row><entry>
 230 pager</><entry> palette</><entry> pidl</><entry> print</><entry> process</>
 231 </row><row><entry>
 232 profile</><entry> progress</><entry>prop</><entry> propsheet</><entry>psapi</>
 233 </row><row><entry>
 234 psdrv</><entry> ras</><entry> rebar</><entry> reg</><entry> region</>
 235 </row><row><entry>
 236 relay</><entry> resource</><entry>richedit</><entry>scroll</><entry>segment</>
 237 </row><row><entry>
 238 seh</><entry>selector</><entry>sendmsg</><entry> server</><entry>setupapi</>
 239 </row><row><entry>
 240 setupx</><entry>shell</><entry> snoop</><entry> sound</><entry>static</>
 241 </row><row><entry>
 242 statusbar</><entry>storage</><entry> stress</><entry> string</><entry>syscolor</>
 243 </row><row><entry>
 244 system</><entry> tab</><entry>tape</><entry>tapi</><entry>task</>
 245 </row><row><entry>
 246 text</><entry>thread</><entry>thunk</><entry>timer</><entry> toolbar</>
 247 </row><row><entry>
 248 toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</><entry>ttydrv</>
 249 </row><row><entry>
 250 tweak</><entry>typelib</><entry> updown</><entry>ver</><entry>virtual</>
 251 </row><row><entry>
 252 vxd</><entry>wave</><entry>win</><entry>win16drv</><entry>win32</>
 253 </row><row><entry>
 254 wing</><entry>wininet</><entry> winsock</><entry> winspool</><entry>wnet</>
 255 </row><row><entry>
 256 x11</><entry> x11drv</>
 257 </row>
 258                 </tbody>
 259                 </tgroup>
 260                 </table>
 261
 262         <para>
 263           For more details about debug channels, check out the
 264           <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
 265             The Wine Developer's Guide</ulink>.
 266         </para>
 267       </sect2>
 268
 269       <sect2>
 270         <title>--dll</title>
 271         <para>
 272
 273         </para>
 274       </sect2>
 275
 276       <sect2>
 277         <title>--dosver</title>
 278         <para>
 279
 280         </para>
 281       </sect2>
 282
 283       <sect2>
 284         <title>--help</title>
 285         <para>
 286
 287         </para>
 288       </sect2>
 289
 290       <sect2 id="managed-parameter">
 291         <title>--managed</title>
 292         <para>
 293
 294         </para>
 295       </sect2>
 296
 297       <sect2>
 298         <title>--version</title>
 299         <para>
 300
 301         </para>
 302       </sect2>
 303
 304       <sect2>
 305         <title>--winver</title>
 306         <para>
 307
 308         </para>
 309       </sect2>
 310     </sect1>
 311   </chapter>
 312
 313 <!-- Keep this comment at the end of the file
 314 Local variables:
 315 mode: sgml
 316 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 317 End:
 318 -->