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.  (As described in the
 116           <link linkend = "config-debug-etc">Debug</link>
 117           section of configuring wine you can
 118           modify what the <parameter>relay</parameter> trace reports).
 119           Logging does slow down Wine
 120           quite a bit, so don't use <parameter>--debugmsg</parameter>
 121           unless you really do want log files.
 122         </para>
 123         <para>
 124           Within each debug channel, you can further specify a
 125           <firstterm>message class</firstterm>, to filter out the
 126           different severities of errors.  The four message classes
 127           are:
 128           <simplelist type="inline">
 129             <member><parameter>trace</parameter></member>
 130             <member><parameter>fixme</parameter></member>
 131             <member><parameter>warn</parameter></member>
 132             <member><parameter>err</parameter></member>
 133           </simplelist>.
 134         </para>
 135         <para>
 136           To turn on a debug channel, use the form
 137           <parameter>class+channel</parameter>.  To turn it off, use
 138           <parameter>class-channel</parameter>.  To list more than one
 139           channel in the same <parameter>--debugmsg</parameter>
 140           option, separate them with commas.  For example, to request
 141           <parameter>warn</parameter> class messages in the
 142           <parameter>heap</parameter> debug channel, you could invoke
 143           <command>wine</command> like this:
 144         </para>
 145         <screen>
 146 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
 147         </screen>
 148         <para>
 149           If you leave off the message class, <command>wine</command>
 150           will display messages from all four classes for that channel:
 151         </para>
 152         <screen>
 153 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
 154         </screen>
 155         <para>
 156           If you wanted to see log messages for everything except the
 157           relay channel, you might do something like this:
 158         </para>
 159         <screen>
 160 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
 161         </screen>
 162         <para>
 163           Here is a master list of all the debug channels and classes
 164           in Wine.  More channels will be added to (or subtracted
 165           from) later versions.
 166         </para>
 167
 168                 <table frame="none"><title>Debug Channels</title>
 169                 <tgroup cols=5 align="left">
 170                 <tbody>
 171 <row><entry>
 172 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
 173 </row><row><entry>
 174 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
 175 </row><row><entry>
 176 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
 177 </row><row><entry>
 178 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
 179 </row><row><entry>
 180 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
 181 </row><row><entry>
 182 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
 183 </row><row><entry>
 184 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
 185 </row><row><entry>
 186 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
 187 </row><row><entry>
 188 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
 189 </row><row><entry>
 190 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
 191 </row><row><entry>
 192 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
 193 </row><row><entry>
 194 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
 195 </row><row><entry>
 196 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
 197 </row><row><entry>
 198 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
 199 </row><row><entry>
 200 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
 201 </row><row><entry>
 202 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
 203 </row><row><entry>
 204 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
 205 </row><row><entry>
 206 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
 207 </row><row><entry>
 208 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
 209 </row><row><entry>
 210 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
 211 </row><row><entry>
 212 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
 213 </row><row><entry>
 214 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
 215 </row><row><entry>
 216 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
 217 </row><row><entry>
 218 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
 219 </row><row><entry>
 220 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
 221 </row><row><entry>
 222 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
 223 </row><row><entry>
 224 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
 225 </row><row><entry>
 226 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
 227 </row><row><entry>
 228 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
 229 </row><row><entry>
 230 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
 231 </row><row><entry>
 232 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
 233 </row><row><entry>
 234 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
 235 </row><row><entry>
 236 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
 237 </row><row><entry>
 238 winspool</><entry>wnet</><entry>x11</>
 239 </row>
 240                 </tbody>
 241                 </tgroup>
 242                 </table>
 243
 244         <para>
 245           For more details about debug channels, check out the
 246           <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
 247             The Wine Developer's Guide</ulink>.
 248         </para>
 249       </sect2>
 250
 251       <sect2>
 252         <title>--dll</title>
 253         <para>
 254           Specifies whether to load the builtin or the native (if
 255           available) version of a DLL.
 256           Example:
 257           <screen>
 258 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
 259           </screen>
 260           See the <link linkend="dll-config">DLL chapter</link> for more details.
 261         </para>
 262       </sect2>
 263
 264       <sect2>
 265         <title>--help</title>
 266         <para>
 267           Shows a small command line help page.
 268         </para>
 269       </sect2>
 270
 271       <sect2>
 272         <title>--version</title>
 273         <para>
 274           Shows the Wine version string. Useful to verify your installation.
 275         </para>
 276       </sect2>
 277     </sect1>
 278
 279     <sect1 id="environment-variables">
 280       <title>Setting Windows/DOS environment variables</title>
 281       <para>
 282         Your program might require some environment variable to be set
 283         properly in order to run successfully.
 284         In this case you need to set this environment variable in the
 285         Linux shell, since Wine will pass on the entire shell environment
 286         variable settings to the Windows environment variable space.
 287         Example for the bash shell (other shells may have a different syntax
 288         !):
 289         <screen>
 290           export MYENVIRONMENTVAR=myenvironmentvarsetting
 291         </screen>
 292         This will make sure your Windows program can access the
 293         MYENVIRONMENTVAR environment variable once you start your program
 294         using Wine.
 295         If you want to have MYENVIRONMENTVAR set permanently, then you can
 296         place the setting into /etc/profile, or also ~/.bashrc in the case of
 297         bash.
 298       </para>
 299       <para>
 300         Note however that there is an exception to the rule:
 301         If you want to change the PATH environment variable, then of
 302         course you can't modify it that way, since this will alter the
 303         Unix PATH environment setting. Instead, you should set the
 304         WINEPATH environment variable. An alternative way to
 305         indicate the content of the DOS PATH environment variable would
 306         be to change the "path" setting in the wine config file's <link
 307         linkend="config-wine">[wine]</link> section.
 308       </para>
 309
 310     </sect1>
 311
 312   </chapter>
 313
 314 <!-- Keep this comment at the end of the file
 315 Local variables:
 316 mode: sgml
 317 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 318 End:
 319 -->