wine/documentation/running.sgml

274 lines
11 KiB
Plaintext

<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>
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 able your program, in the Unix console were you're started
your program, 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, many of them
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. 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 might 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>
</para>
</sect2>
<sect2>
<title>--help</title>
<para>
</para>
</sect2>
<sect2>
<title>--version</title>
<para>
</para>
</sect2>
</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:
-->