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