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