Sweden-Number/documentation/running.sgml

653 lines
24 KiB
Plaintext

<chapter id="running">
<title>Running Wine</title>
<para>
Written by &name-john-sheets; <email>&email-john-sheets;</email>
</para>
<para>
Extended by &name-mike-hearn; <email>&email-mike-hearn;</email>, &name-eric-pouech; <email>&email-eric-pouech;</email>
</para>
<sect1 id="basic-usage">
<title>Basic usage: applications and control panel applets</title>
<para>
Assuming you are using a fake windows installation, you install
applications into Wine in the same way you would in Windows:
by running the installer. You can just accept the defaults
for where to install, most installers will default to "C:\Program Files",
which is fine. If the application installer requests it, you may find that
Wine creates icons on your desktop and in your app menu. If that happens, you
can start the app by clicking on them.
</para>
<para>
The standard way to uninstall things is for the application to provide an
uninstaller, usually registered with the "Add/Remove Programs" control panel
applet. Unfortunately as of the time of writing, Wine doesn't provide an
Add/Remove control panel applet, so you'll have to run the uninstall manually, either
from the menu or from the command line.
</para>
<para>
Some programs install associated control panel applets, examples of this would be
Internet Explorer and QuickTime. You can access the Wine control panel by running:
</para>
<screen>
<prompt>$</prompt> <userinput>wine control</userinput>
</screen>
<para>
which will open a window with the installed control panel applets in it, as in Windows.
</para>
<para>
If the application doesn't install menu or desktop items, you'll need to run the app
from the command line. Remembering where you installed to, something like:
</para>
<screen>
<prompt>$</prompt> <userinput>wine "c:\program files\appname\appname.exe"</userinput>
</screen>
<para>
will probably do the trick. The path isn't case sensitive, but remember to include the double quotes.
Some programs don't always use obvious naming for their directories and EXE files, so you might have
to look inside the program files directory to see what it put where
</para>
</sect1>
<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>
For details on running text mode (CUI) executables, read the
<link linkend="CUI-programs">section</link> below.
</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>
<sect1 id="CUI-programs">
<title>Text mode programs (CUI: Console User Interface)</title>
<para>Text mode programs are program which output is only made
out of text (surprise!). In Windows terminolgy, they are
called CUI (Console User Interface) executables, by opposition
to GUI (Graphical User Interface) executables. Win32 API
provide a complete set of APIs to handle this situation, which
goes from basic features like text printing, up to high level
functionnalities (like full screen editing, color support,
cursor motion, mouse support), going through features like
line editing or raw/cooked input stream support
</para>
<para>
Given the wide scope of features above, and the current usage
in Un*x world, Wine comes out with three different ways for
running a console program (aka a CUI executable):
<itemizedlist>
<listitem>
<para>bare streams</para>
</listitem>
<listitem>
<para>wineconsole with user backend</para>
</listitem>
<listitem>
<para>wineconsole with curses backend</para>
</listitem>
</itemizedlist>
</para>
<para>The names here are a bit obscure. "bare streams" means
that no extra support of wine is provide to map between the
unix console access and Windows console access. The two other
ways require the use of a specific Wine program (wineconsole)
which provide extended facilities. The following table
describes what you can do (and cannot do) with those three
ways.
<table>
<title>Basic differences in consoles</title>
<tgroup cols="4" align="left">
<thead>
<row>
<entry>Function</entry>
<entry>Bare streams</entry>
<entry>Wineconsole &amp; user backend</entry>
<entry>Wineconsole &amp; curses backend</entry>
</row>
</thead>
<tbody>
<row>
<entry>How to run (assuming executable is called foo.exe)</entry>
<entry><msgtext>
<screen><prompt>$</prompt> <userinput>wine foo.exe</userinput></screen>
</msgtext></entry>
<entry><msgtext>
<screen><prompt>$</prompt> <userinput>wineconsole -- --backend=user foo.exe</userinput></screen>
</msgtext></entry>
<entry><msgtext>
<screen><prompt>$</prompt> <userinput>wineconsole foo.exe</userinput></screen>
</msgtext>You can also use --backend=curses as an option</entry>
</row>
<row>
<entry>Good support for line oriented CUI applications
(which print information line after line)
</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Good support for full screen CUI
applications (including but not limited to color
support, mouse support...)</entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Can be run even if X11 is not running</entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
<row>
<entry>Implementation</entry>
<entry>Maps the standard Windows streams to the
standard Unix streams (stdin/stdout/stderr)
</entry>
<entry>
Wineconsole will create a new Window (hence
requiring the USER32 DLL is available) where all
information will be displayed
</entry>
<entry>
Wineconsole will use existing unix console
(from which the program is run) and with the help of
the (n)curses library take control of all the terminal
surface for interacting with the user
</entry>
</row>
<row>
<entry>Known limitations</entry>
<entry></entry>
<entry></entry>
<entry>
Will produce strange behavior if two (or more)
Windows consoles are used on the same Un*x terminal.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<sect2 id="CUI-programs-config">
<title>Configuration of CUI executables</title>
<para>
When wineconsole is used, several configuration options are
available. Wine (as Windows do) stores, on a per application
basis, several options in the registry. This let a user, for
example, define the default screen-buffer size he would like
to have for a given application.
</para>
<para>
As of today, only the USER backend allows you to edit those
options (we don't recommend editing by hand the registry
contents). This edition is fired when a user right click in
the console (this popups a menu), where you can either
choose from:
<itemizedlist>
<listitem>
<para>
Default: this will edit the settings shared by all
applications which haven't been configured yet. So,
when an application is first run (on your machine,
under your account) in wineconsole, wineconsole will
inherit this default settings for the
application. Afterwards, the application will have its
own settings, that you'll be able to modify at your will.
</para>
<para>
Properties: this will edit the application's
settings. When you're done, with the edition, you'll
be prompted whether you want to:
<orderedlist>
<listitem>
<para>
Keep these modified settings only for this
session (next time you run the application, you
will not see the modification you've just made).
</para>
</listitem>
<listitem>
<para>
Use the settings for this session and save them
as well, so that next you run your application,
you'll use these new settings again.
</para>
</listitem>
</orderedlist>
</para>
</listitem>
</itemizedlist>
</para>
<para>
Here's the list of the items you can configure, and their
meanings:
<table>
<title>Wineconsole configuration options</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry>Configuration option</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry>Cursor's size</entry>
<entry>
Defines the size of the cursor. Three options are
available: small (33% of character height), medium
(66%) and large (100%)
</entry>
</row>
<row>
<entry>Popup menu</entry>
<entry>
It's been said earlier that wineconsole
configuration popup was triggered using a right
click in the console's window. However, this can
be an issue when the application you run inside
wineconsole expects the right click events to be
sent to it. By ticking control or shift you select
additional modifiers on the right click for
opening the popup. For example, ticking shift will
send events to the application when you right
click the window without shift being hold down,
and open the window when you right-click while
shift being hold down.
</entry>
</row>
<row>
<entry>Quick edit</entry>
<entry>
This tick box lets you decide whether left-click
mouse events shall be interpreted as events to be
sent to the underlying application (tick off) or
as a selection of rectangular part of the screen
to be later on copied onto the clipboard (tick on).
</entry>
</row>
<row>
<entry>History</entry>
<entry>
This lets you pick up how many commands you want
the console to recall. You can also drive whether
you want, when entering several times the same
command - potentially intertwened with others -
whether you want to store all of them (tick off)
or only the last one (tick on).
</entry>
</row>
<row>
<entry>Police</entry>
<entry>
The Police property sheet allows you to pick the
default font for the console (font file, size,
background and foreground color).
</entry>
</row>
<row>
<entry>Screenbuffer &amp; window size</entry>
<entry>
The console as you see it is made of two different
parts. On one hand there's the screenbuffer which
contains all the information your application puts
on the screen, and the window which displays a
given area of this screen buffer. Note that the
window is always smaller or of the same size than
the screen buffer. Having a stricly smaller window
size will put on scrollbars on the window so that
you can see the whole screenbuffer's content.
</entry>
</row>
<row>
<entry>Close on exit</entry>
<entry>
If it's ticked, then the wineconsole will exit
when the application within terminates. Otherwise,
it'll remain opened until the user manually closes
it: this allows seeing the latest information of a
program after it has terminated.
</entry>
</row>
<row>
<entry>Edition mode</entry>
<entry>
<msgtext>
<para>
When the user enter commands, he or she can
choose between several edition modes:
<itemizedlist>
<listitem>
<para>
Emacs: the same keybindings as under
emacs are available. For example, Ctrl-A
will bring the cursor to the beginning
of the edition line. See your emacs
manual for the details of the commands.
</para>
</listitem>
<listitem>
<para>
Win32: this are the standard Windows
console key-bindings (mainly using
arrows).
</para>
</listitem>
</itemizedlist>
</para>
</msgtext>
</entry>
</row>
</tbody>
</tgroup>
</table>
</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:
-->