2 <title>Running Wine</title>
5 Written by &name-john-sheets; <email>&email-john-sheets;</email>
8 <sect1 id="running-wine">
9 <title>How to run Wine</title>
11 Wine is a very complicated piece of software with many ways to
12 adjust how it runs. With very few exceptions, you can
13 activate the same set of features through the <link
14 linkend="configuring">configuration file </link> as you can
15 with command-line parameters. In this chapter, we'll briefly
16 discuss these parameters, and match them up with their
17 corresponding configuration variables.
21 You can invoke the <command>wine --help</command> command to
22 get a listing of all Wine's command-line parameters:
26 Usage: ./wine [options] program_name [arguments]
29 --debugmsg name Turn debugging-messages on or off
30 --dll name Enable or disable built-in DLLs
31 --help,-h Show this help message
32 --version,-v Display the Wine version
37 You can specify as many options as you want, if any.
38 Typically, you will want to have your configuration file set
39 up with a sensible set of defaults; in this case, you can run
40 <command>wine</command> without explicitly listing any
41 options. In rare cases, you might want to override certain
42 parameters on the command line.
45 After the options, you should put the name of the file you
46 want <command>wine</command> to execute. If the executable is
47 in the <parameter>Path</parameter> parameter in the
48 configuration file, you can simply give the executable file
49 name. However, if the executable is not in
50 <parameter>Path</parameter>, you must give the full path to
51 the executable (in Windows format, not UNIX format!). For
52 example, given a <parameter>Path</parameter> of the following:
56 "Path"="c:\\windows;c:\\windows\\system;e:\\;e:\\test;f:\\"
59 You could run the file
60 <filename>c:\windows\system\foo.exe</filename> with:
63 <prompt>$</prompt> <userinput>wine foo.exe</userinput>
66 However, you would have to run the file
67 <filename>c:\myapps\foo.exe</filename> with this command:
70 <prompt>$</prompt> <userinput>wine c:\\myapps\\foo.exe</userinput>
73 (note the backslash-escaped "\" !)
77 If you want to run a console program (aka a CUI executable), use
78 <command>wineconsole</command> instead of <command>wine</command>
79 to start it. It will display the program in a separate Window
80 (this requires X11 to be run). If you don't, you'll still be able
81 to run your program directly in the Unix console where you started it,
82 but with very limited capacities (so your program might work,
83 but your mileage may vary). This shall be improved in the future.
87 <sect1 id="command-line-options">
88 <title>Command-Line Options</title>
90 <sect2 id="config-parameter">
91 <title>--debugmsg [channels]</title>
93 Wine isn't perfect, and many Windows applications still
94 don't run without bugs under Wine (but then, a lot of programs
95 don't run without bugs under native Windows either!). To
96 make it easier for people to track down the causes behind
97 each bug, Wine provides a number of <firstterm>debug
98 channels</firstterm> that you can tap into.
101 Each debug channel, when activated, will trigger logging
102 messages to be displayed to the console where you invoked
103 <command>wine</command>. From there you can redirect the
104 messages to a file and examine it at your leisure. But be
105 forewarned! Some debug channels can generate incredible
106 volumes of log messages. Among the most prolific offenders
107 are <parameter>relay</parameter> which spits out a log
108 message every time a win32 function is called,
109 <parameter>win</parameter> which tracks windows message
110 passing, and of course <parameter>all</parameter> which is
111 an alias for every single debug channel that exists. For a
112 complex application, your debug logs can easily top 1 MB and
113 higher. A <parameter>relay</parameter> trace can often
114 generate more than 10 MB of log messages, depending on how
115 long you run the application. (As described in the
116 <link linkend = "config-debug-etc">Debug</link>
117 section of configuring wine you can
118 modify what the <parameter>relay</parameter> trace reports).
119 Logging does slow down Wine
120 quite a bit, so don't use <parameter>--debugmsg</parameter>
121 unless you really do want log files.
124 Within each debug channel, you can further specify a
125 <firstterm>message class</firstterm>, to filter out the
126 different severities of errors. The four message classes
128 <simplelist type="inline">
129 <member><parameter>trace</parameter></member>
130 <member><parameter>fixme</parameter></member>
131 <member><parameter>warn</parameter></member>
132 <member><parameter>err</parameter></member>
136 To turn on a debug channel, use the form
137 <parameter>class+channel</parameter>. To turn it off, use
138 <parameter>class-channel</parameter>. To list more than one
139 channel in the same <parameter>--debugmsg</parameter>
140 option, separate them with commas. For example, to request
141 <parameter>warn</parameter> class messages in the
142 <parameter>heap</parameter> debug channel, you could invoke
143 <command>wine</command> like this:
146 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
149 If you leave off the message class, <command>wine</command>
150 will display messages from all four classes for that channel:
153 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
156 If you wanted to see log messages for everything except the
157 relay channel, you might do something like this:
160 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
163 Here is a master list of all the debug channels and classes
164 in Wine. More channels will be added to (or subtracted
165 from) later versions.
168 <table frame="none"><title>Debug Channels</title>
169 <tgroup cols=5 align="left">
172 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
174 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
176 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
178 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
180 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
182 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
184 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
186 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
188 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
190 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
192 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
194 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
196 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
198 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
200 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
202 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
204 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
206 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
208 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
210 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
212 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
214 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
216 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
218 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
220 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
222 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
224 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
226 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
228 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
230 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
232 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
234 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
236 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
238 winspool</><entry>wnet</><entry>x11</>
245 For more details about debug channels, check out the
246 <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
247 The Wine Developer's Guide</ulink>.
254 Specifies whether to load the builtin or the native (if
255 available) version of a DLL.
258 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
260 See the <link linkend="dll-config">DLL chapter</link> for more details.
265 <title>--help</title>
267 Shows a small command line help page.
272 <title>--version</title>
274 Shows the Wine version string. Useful to verify your installation.
279 <sect1 id="environment-variables">
280 <title>Setting Windows/DOS environment variables</title>
282 Your program might require some environment variable to be set
283 properly in order to run successfully.
284 In this case you need to set this environment variable in the
285 Linux shell, since Wine will pass on the entire shell environment
286 variable settings to the Windows environment variable space.
287 Example for the bash shell (other shells may have a different syntax
290 export MYENVIRONMENTVAR=myenvironmentvarsetting
292 This will make sure your Windows program can access the
293 MYENVIRONMENTVAR environment variable once you start your program
295 If you want to have MYENVIRONMENTVAR set permanently, then you can
296 place the setting into /etc/profile, or also ~/.bashrc in the case of
300 Note however that there is an exception to the rule:
301 If you want to change the PATH environment variable, then of
302 course you can't modify it that way, since this will alter the
303 Unix PATH environment setting. Instead, you should set the
304 WINEPATH environment variable. An alternative way to
305 indicate the content of the DOS PATH environment variable would
306 be to change the "path" setting in the wine config file's <link
307 linkend="config-wine">[wine]</link> section.
314 <!-- Keep this comment at the end of the file
317 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
projects / wine / blob