documentation/running.sgml - wine - Git at Google

   <chapter id="running">
     <title>Running Wine</title>

     <para>
       Written by &name-john-sheets; <email>&email-john-sheets;</email>
     </para>

     <sect1 id="running-wine">
       <title>How to run Wine</title>
       <para>
         Wine is a very complicated piece of software with many ways to
         adjust how it runs.  With very few exceptions, you can
         activate the same set of features through the <link
         linkend="configuring">configuration file </link> as you can
         with command-line parameters.  In this chapter, we'll briefly
         discuss these parameters, and match them up with their
         corresponding configuration variables.
       </para>

       <para>
         You can invoke the <command>wine --help</command> command to
         get a listing of all Wine's command-line parameters:
       </para>
       <para>
         <screen>
 Usage: ./wine [options] program_name [arguments]

 Options:
    --debugmsg name  Turn debugging-messages on or off
    --dll name       Enable or disable built-in DLLs
    --help,-h        Show this help message
    --version,-v     Display the Wine version
         </screen>
       </para>

       <para>
         You can specify as many options as you want, if any.
         Typically, you will want to have your configuration file set
         up with a sensible set of defaults; in this case, you can run
         <command>wine</command> without explicitly listing any
         options.  In rare cases, you might want to override certain
         parameters on the command line.
       </para>
       <para>
         After the options, you should put the name of the file you
         want <command>wine</command> to execute.  If the executable is
         in the <parameter>Path</parameter> parameter in the
         configuration file, you can simply give the executable file
         name.  However, if the executable is not in
         <parameter>Path</parameter>, you must give the full path to
         the executable (in Windows format, not UNIX format!).  For
         example, given a <parameter>Path</parameter> of the following:
       </para>
       <screen>
 [wine]
 "Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"
       </screen>
       <para>
         You could run the file
         <filename>c:\windows\system\foo.exe</filename> with:
       </para>
       <screen>
 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
       </screen>
       <para>
         However, you would have to run the file
         <filename>c:\myapps\foo.exe</filename> with this command:
       </para>
       <screen>
 <prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
       </screen>
       <para>
       (note the backslash-escaped "\" !)
       </para>

       <para>
         If you want to run a console program (aka a CUI executable), use
 	<command>wineconsole</command> instead of <command>wine</command>
 	to start it. It will display the program in a separate Window
 	(this requires X11 to be run). If you don't, you'll still be able
 	to run your program directly in the Unix console where you started it,
 	but with very limited capacities (so your program might work,
 	but your mileage may vary). This shall be improved in the future.
       </para>
     </sect1>

     <sect1 id="command-line-options">
       <title>Command-Line Options</title>

       <sect2 id="config-parameter">
         <title>--debugmsg [channels]</title>
         <para>
           Wine isn't perfect, and many Windows applications still
           don't run without bugs under Wine (but then, a lot of programs
           don't run without bugs under native Windows either!).  To
           make it easier for people to track down the causes behind
           each bug, Wine provides a number of <firstterm>debug
           channels</firstterm> that you can tap into.
         </para>
         <para>
           Each debug channel, when activated, will trigger logging
           messages to be displayed to the console where you invoked
           <command>wine</command>.  From there you can redirect the
           messages to a file and examine it at your leisure.  But be
           forewarned!  Some debug channels can generate incredible
           volumes of log messages.  Among the most prolific offenders
           are <parameter>relay</parameter> which spits out a log
           message every time a win32 function is called,
           <parameter>win</parameter> which tracks windows message
           passing, and of course <parameter>all</parameter> which is
           an alias for every single debug channel that exists.  For a
           complex application, your debug logs can easily top 1 MB and
           higher.  A <parameter>relay</parameter> trace can often
           generate more than 10 MB of log messages, depending on how
           long you run the application.  (As described in the
           <link linkend = "config-debug-etc">Debug</link>
           section of configuring wine you can
           modify what the <parameter>relay</parameter> trace reports).
           Logging does slow down Wine
           quite a bit, so don't use <parameter>--debugmsg</parameter>
           unless you really do want log files.
         </para>
         <para>
           Within each debug channel, you can further specify a
           <firstterm>message class</firstterm>, to filter out the
           different severities of errors.  The four message classes
           are:
           <simplelist type="inline">
             <member><parameter>trace</parameter></member>
             <member><parameter>fixme</parameter></member>
             <member><parameter>warn</parameter></member>
             <member><parameter>err</parameter></member>
           </simplelist>.
         </para>
         <para>
           To turn on a debug channel, use the form
           <parameter>class+channel</parameter>.  To turn it off, use
           <parameter>class-channel</parameter>.  To list more than one
           channel in the same <parameter>--debugmsg</parameter>
           option, separate them with commas.  For example, to request
           <parameter>warn</parameter> class messages in the
           <parameter>heap</parameter> debug channel, you could invoke
           <command>wine</command> like this:
         </para>
         <screen>
 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
         </screen>
         <para>
           If you leave off the message class, <command>wine</command>
           will display messages from all four classes for that channel:
         </para>
         <screen>
 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
         </screen>
         <para>
           If you wanted to see log messages for everything except the
           relay channel, you might do something like this:
         </para>
         <screen>
 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
         </screen>
         <para>
           Here is a master list of all the debug channels and classes
           in Wine.  More channels will be added to (or subtracted
           from) later versions.
         </para>

 		<table frame="none"><title>Debug Channels</title>
 		<tgroup cols=5 align="left">
 		<tbody>
 <row><entry>
 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
 </row><row><entry>
 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
 </row><row><entry>
 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
 </row><row><entry>
 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
 </row><row><entry>
 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
 </row><row><entry>
 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
 </row><row><entry>
 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
 </row><row><entry>
 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
 </row><row><entry>
 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
 </row><row><entry>
 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
 </row><row><entry>
 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
 </row><row><entry>
 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
 </row><row><entry>
 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
 </row><row><entry>
 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
 </row><row><entry>
 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
 </row><row><entry>
 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
 </row><row><entry>
 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
 </row><row><entry>
 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
 </row><row><entry>
 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
 </row><row><entry>
 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
 </row><row><entry>
 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
 </row><row><entry>
 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
 </row><row><entry>
 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
 </row><row><entry>
 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
 </row><row><entry>
 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
 </row><row><entry>
 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
 </row><row><entry>
 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
 </row><row><entry>
 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
 </row><row><entry>
 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
 </row><row><entry>
 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
 </row><row><entry>
 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
 </row><row><entry>
 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
 </row><row><entry>
 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
 </row><row><entry>
 winspool</><entry>wnet</><entry>x11</>
 </row>
 		</tbody>
 		</tgroup>
 		</table>

         <para>
           For more details about debug channels, check out the
           <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
             The Wine Developer's Guide</ulink>.
         </para>
       </sect2>

       <sect2>
         <title>--dll</title>
         <para>
           Specifies whether to load the builtin or the native (if
 	  available) version of a DLL.
 	  Example:
 	  <screen>
 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
           </screen>
 	  See the <link linkend="dll-config">DLL chapter</link> for more details.
         </para>
       </sect2>

       <sect2>
         <title>--help</title>
         <para>
           Shows a small command line help page.
         </para>
       </sect2>

       <sect2>
         <title>--version</title>
         <para>
 	  Shows the Wine version string. Useful to verify your installation.
         </para>
       </sect2>
     </sect1>

     <sect1 id="environment-variables">
       <title>Setting Windows/DOS environment variables</title>
       <para>
         Your program might require some environment variable to be set
 	properly in order to run successfully.
 	In this case you need to set this environment variable in the
 	Linux shell, since Wine will pass on the entire shell environment
 	variable settings to the Windows environment variable space.
 	Example for the bash shell (other shells may have a different syntax
 	!):
         <screen>
 	  export MYENVIRONMENTVAR=myenvironmentvarsetting
 	</screen>
 	This will make sure your Windows program can access the
 	MYENVIRONMENTVAR environment variable once you start your program
 	using Wine.
 	If you want to have MYENVIRONMENTVAR set permanently, then you can
 	place the setting into /etc/profile, or also ~/.bashrc in the case of
 	bash.
       </para>
       <para>
         Note however that there is an exception to the rule:
 	If you want to change the PATH environment variable, then of
 	course you can't modify it that way, since this will alter the
 	Unix PATH environment setting. Instead, you should set the
 	WINEPATH environment variable. An alternative way to
 	indicate the content of the DOS PATH environment variable would
 	be to change the "path" setting in the wine config file's <link
 	linkend="config-wine">[wine]</link> section.
       </para>

     </sect1>

   </chapter>

 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
 End:
 -->
	<chapter id="running">
	<title>Running Wine</title>

	<para>
	Written by &name-john-sheets; <email>&email-john-sheets;</email>
	</para>

	<sect1 id="running-wine">
	<title>How to run Wine</title>
	<para>
	Wine is a very complicated piece of software with many ways to
	adjust how it runs. With very few exceptions, you can
	activate the same set of features through the <link
	linkend="configuring">configuration file </link> as you can
	with command-line parameters. In this chapter, we'll briefly
	discuss these parameters, and match them up with their
	corresponding configuration variables.
	</para>

	<para>
	You can invoke the <command>wine --help</command> command to
	get a listing of all Wine's command-line parameters:
	</para>
	<para>
	<screen>
	Usage: ./wine [options] program_name [arguments]

	Options:
	--debugmsg name Turn debugging-messages on or off
	--dll name Enable or disable built-in DLLs
	--help,-h Show this help message
	--version,-v Display the Wine version
	</screen>
	</para>

	<para>
	You can specify as many options as you want, if any.
	Typically, you will want to have your configuration file set
	up with a sensible set of defaults; in this case, you can run
	<command>wine</command> without explicitly listing any
	options. In rare cases, you might want to override certain
	parameters on the command line.
	</para>
	<para>
	After the options, you should put the name of the file you
	want <command>wine</command> to execute. If the executable is
	in the <parameter>Path</parameter> parameter in the
	configuration file, you can simply give the executable file
	name. However, if the executable is not in
	<parameter>Path</parameter>, you must give the full path to
	the executable (in Windows format, not UNIX format!). For
	example, given a <parameter>Path</parameter> of the following:
	</para>
	<screen>
	[wine]
	"Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"
	</screen>
	<para>
	You could run the file
	<filename>c:\windows\system\foo.exe</filename> with:
	</para>
	<screen>
	<prompt>$</prompt> <userinput>wine foo.exe</userinput>
	</screen>
	<para>
	However, you would have to run the file
	<filename>c:\myapps\foo.exe</filename> with this command:
	</para>
	<screen>
	<prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
	</screen>
	<para>
	(note the backslash-escaped "\" !)
	</para>

	<para>
	If you want to run a console program (aka a CUI executable), use
	<command>wineconsole</command> instead of <command>wine</command>
	to start it. It will display the program in a separate Window
	(this requires X11 to be run). If you don't, you'll still be able
	to run your program directly in the Unix console where you started it,
	but with very limited capacities (so your program might work,
	but your mileage may vary). This shall be improved in the future.
	</para>
	</sect1>

	<sect1 id="command-line-options">
	<title>Command-Line Options</title>

	<sect2 id="config-parameter">
	<title>--debugmsg [channels]</title>
	<para>
	Wine isn't perfect, and many Windows applications still
	don't run without bugs under Wine (but then, a lot of programs
	don't run without bugs under native Windows either!). To
	make it easier for people to track down the causes behind
	each bug, Wine provides a number of <firstterm>debug
	channels</firstterm> that you can tap into.
	</para>
	<para>
	Each debug channel, when activated, will trigger logging
	messages to be displayed to the console where you invoked
	<command>wine</command>. From there you can redirect the
	messages to a file and examine it at your leisure. But be
	forewarned! Some debug channels can generate incredible
	volumes of log messages. Among the most prolific offenders
	are <parameter>relay</parameter> which spits out a log
	message every time a win32 function is called,
	<parameter>win</parameter> which tracks windows message
	passing, and of course <parameter>all</parameter> which is
	an alias for every single debug channel that exists. For a
	complex application, your debug logs can easily top 1 MB and
	higher. A <parameter>relay</parameter> trace can often
	generate more than 10 MB of log messages, depending on how
	long you run the application. (As described in the
	<link linkend = "config-debug-etc">Debug</link>
	section of configuring wine you can
	modify what the <parameter>relay</parameter> trace reports).
	Logging does slow down Wine
	quite a bit, so don't use <parameter>--debugmsg</parameter>
	unless you really do want log files.
	</para>
	<para>
	Within each debug channel, you can further specify a
	<firstterm>message class</firstterm>, to filter out the
	different severities of errors. The four message classes
	are:
	<simplelist type="inline">
	<member><parameter>trace</parameter></member>
	<member><parameter>fixme</parameter></member>
	<member><parameter>warn</parameter></member>
	<member><parameter>err</parameter></member>
	</simplelist>.
	</para>
	<para>
	To turn on a debug channel, use the form
	<parameter>class+channel</parameter>. To turn it off, use
	<parameter>class-channel</parameter>. To list more than one
	channel in the same <parameter>--debugmsg</parameter>
	option, separate them with commas. For example, to request
	<parameter>warn</parameter> class messages in the
	<parameter>heap</parameter> debug channel, you could invoke
	<command>wine</command> like this:
	</para>
	<screen>
	<prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
	</screen>
	<para>
	If you leave off the message class, <command>wine</command>
	will display messages from all four classes for that channel:
	</para>
	<screen>
	<prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
	</screen>
	<para>
	If you wanted to see log messages for everything except the
	relay channel, you might do something like this:
	</para>
	<screen>
	<prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
	</screen>
	<para>
	Here is a master list of all the debug channels and classes
	in Wine. More channels will be added to (or subtracted
	from) later versions.
	</para>

	<table frame="none"><title>Debug Channels</title>
	<tgroup cols=5 align="left">
	<tbody>
	<row><entry>
	all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
	</row><row><entry>
	atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
	</row><row><entry>
	cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
	</row><row><entry>
	comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
	</row><row><entry>
	crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
	</row><row><entry>
	ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
	</row><row><entry>
	dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
	</row><row><entry>
	driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
	</row><row><entry>
	event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
	</row><row><entry>
	gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
	</row><row><entry>
	hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
	</row><row><entry>
	imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
	</row><row><entry>
	int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
	</row><row><entry>
	ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
	</row><row><entry>
	ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
	</row><row><entry>
	mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
	</row><row><entry>
	mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
	</row><row><entry>
	mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
	</row><row><entry>
	monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
	</row><row><entry>
	nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
	</row><row><entry>
	opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
	</row><row><entry>
	process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
	</row><row><entry>
	psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
	</row><row><entry>
	region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
	</row><row><entry>
	segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
	</row><row><entry>
	setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
	</row><row><entry>
	static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
	</row><row><entry>
	syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
	</row><row><entry>
	task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
	</row><row><entry>
	toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
	</row><row><entry>
	ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
	</row><row><entry>
	virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
	</row><row><entry>
	win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
	</row><row><entry>
	winspool</><entry>wnet</><entry>x11</>
	</row>
	</tbody>
	</tgroup>
	</table>

	<para>
	For more details about debug channels, check out the
	<ulink url="http://wine.codeweavers.com/docs/wine-devel/">
	The Wine Developer's Guide</ulink>.
	</para>
	</sect2>

	<sect2>
	<title>--dll</title>
	<para>
	Specifies whether to load the builtin or the native (if
	available) version of a DLL.
	Example:
	<screen>
	<prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
	</screen>
	See the <link linkend="dll-config">DLL chapter</link> for more details.
	</para>
	</sect2>

	<sect2>
	<title>--help</title>
	<para>
	Shows a small command line help page.
	</para>
	</sect2>

	<sect2>
	<title>--version</title>
	<para>
	Shows the Wine version string. Useful to verify your installation.
	</para>
	</sect2>
	</sect1>

	<sect1 id="environment-variables">
	<title>Setting Windows/DOS environment variables</title>
	<para>
	Your program might require some environment variable to be set
	properly in order to run successfully.
	In this case you need to set this environment variable in the
	Linux shell, since Wine will pass on the entire shell environment
	variable settings to the Windows environment variable space.
	Example for the bash shell (other shells may have a different syntax
	!):
	<screen>
	export MYENVIRONMENTVAR=myenvironmentvarsetting
	</screen>
	This will make sure your Windows program can access the
	MYENVIRONMENTVAR environment variable once you start your program
	using Wine.
	If you want to have MYENVIRONMENTVAR set permanently, then you can
	place the setting into /etc/profile, or also ~/.bashrc in the case of
	bash.
	</para>
	<para>
	Note however that there is an exception to the rule:
	If you want to change the PATH environment variable, then of
	course you can't modify it that way, since this will alter the
	Unix PATH environment setting. Instead, you should set the
	WINEPATH environment variable. An alternative way to
	indicate the content of the DOS PATH environment variable would
	be to change the "path" setting in the wine config file's <link
	linkend="config-wine">[wine]</link> section.
	</para>

	</sect1>

	</chapter>

	<!-- Keep this comment at the end of the file
	Local variables:
	mode: sgml
	sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
	End:
	-->