Document [WinMM] drivers options.

[wine] / documentation / running.sgml

  <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>
    </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>
        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:
-->