| <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 & user backend</entry> |
| <entry>Wineconsole & 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 & 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: |
| --> |
