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