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. Logging does slow down Wine
116 quite a bit, so don't use <parameter>--debugmsg</parameter>
117 unless you really do want log files.
120 Within each debug channel, you can further specify a
121 <firstterm>message class</firstterm>, to filter out the
122 different severities of errors. The four message classes
124 <simplelist type="inline">
125 <member><parameter>trace</parameter></member>
126 <member><parameter>fixme</parameter></member>
127 <member><parameter>warn</parameter></member>
128 <member><parameter>err</parameter></member>
132 To turn on a debug channel, use the form
133 <parameter>class+channel</parameter>. To turn it off, use
134 <parameter>class-channel</parameter>. To list more than one
135 channel in the same <parameter>--debugmsg</parameter>
136 option, separate them with commas. For example, to request
137 <parameter>warn</parameter> class messages in the
138 <parameter>heap</parameter> debug channel, you could invoke
139 <command>wine</command> like this:
142 <prompt>$</prompt> <userinput>wine --debugmsg warn+heap <replaceable>program_name</replaceable></userinput>
145 If you leave off the message class, <command>wine</command>
146 will display messages from all four classes for that channel:
149 <prompt>$</prompt> <userinput>wine --debugmsg +heap <replaceable>program_name</replaceable></userinput>
152 If you wanted to see log messages for everything except the
153 relay channel, you might do something like this:
156 <prompt>$</prompt> <userinput>wine --debugmsg +all,-relay <replaceable>program_name</replaceable></userinput>
159 Here is a master list of all the debug channels and classes
160 in Wine. More channels will be added to (or subtracted
161 from) later versions.
164 <table frame="none"><title>Debug Channels</title>
165 <tgroup cols=5 align="left">
168 all</><entry>accel</><entry>advapi</><entry>animate</><entry>aspi</>
170 atom</><entry>avifile</><entry> bitblt</><entry> bitmap</><entry> caret</>
172 cdrom</><entry>class</><entry> clipboard</><entry> clipping</><entry>combo</>
174 comboex</><entry> comm</><entry>commctrl</><entry>commdlg</><entry> console</>
176 crtdll</><entry>cursor</><entry>datetime</><entry>dc</><entry> ddeml</>
178 ddraw</><entry> debug</><entry> debugstr</><entry>delayhlp</><entry>dialog</>
180 dinput</><entry>dll</><entry> dosfs</><entry>dosmem</><entry>dplay</>
182 driver</><entry>dsound</><entry>edit</><entry>elfdll</><entry>enhmetafile</>
184 event</><entry>exec</><entry>file</><entry>fixup</><entry>font</>
186 gdi</><entry> global</><entry>graphics</><entry> header</><entry>heap</>
188 hook</><entry>hotkey</><entry>icmp</><entry>icon</><entry>imagehlp</>
190 imagelist</><entry> imm</><entry>int</><entry>int10</><entry>int16</>
192 int17</><entry>int19</><entry>int21</><entry>int31</><entry> io</>
194 ipaddress</><entry>joystick</><entry>key</><entry>keyboard</><entry>loaddll</>
196 ldt</><entry>listbox</><entry>listview</><entry>local</><entry>mci</>
198 mcianim</><entry>mciavi</><entry>mcicda</><entry>mcimidi</><entry>mciwave</>
200 mdi</><entry>menu</><entry>message</><entry>metafile</><entry>midi</>
202 mmaux</><entry>mmio</><entry>mmsys</><entry>mmtime</><entry>module</>
204 monthcal</><entry>mpr</><entry>msacm</><entry>msg</><entry>msvideo</>
206 nativefont</><entry>nonclient</><entry>ntdll</><entry>odbc</><entry>ole</>
208 opengl</><entry>pager</><entry>palette</><entry>pidl</><entry>print</>
210 process</><entry>profile</><entry>progress</><entry>prop</><entry>propsheet</>
212 psapi</><entry>psdrv</><entry>ras</><entry>rebar</><entry>reg</>
214 region</><entry>relay</><entry>resource</><entry>richedit</><entry>scroll</>
216 segment</><entry>seh</><entry>selector</><entry>sendmsg</><entry>server</>
218 setupapi</><entry>setupx</><entry>shell</><entry>snoop</><entry>sound</>
220 static</><entry>statusbar</><entry>storage</><entry>stress</><entry>string</>
222 syscolor</><entry>system</><entry>tab</><entry>tape</><entry>tapi</>
224 task</><entry>text</><entry>thread</><entry>thunk</><entry>timer</>
226 toolbar</><entry>toolhelp</><entry>tooltips</><entry>trackbar</><entry>treeview</>
228 ttydrv</><entry>tweak</><entry>typelib</><entry>updown</><entry>ver</>
230 virtual</><entry>vxd</><entry>wave</><entry>win</><entry>win16drv</>
232 win32</><entry>winedbg</><entry>wing</><entry>wininet</><entry>winsock</>
234 winspool</><entry>wnet</><entry>x11</>
241 For more details about debug channels, check out the
242 <ulink url="http://wine.codeweavers.com/docs/wine-devel/">
243 The Wine Developer's Guide</ulink>.
250 Specifies whether to load the builtin or the native (if
251 available) version of a DLL.
254 <prompt>$</prompt> <userinput>wine --dll setupx=n foo.exe</userinput>
256 See the <link linkend="dlls">DLL chapter</link> for more details.
261 <title>--help</title>
263 Shows a small command line help page.
268 <title>--version</title>
270 Shows the Wine version string. Useful to verify your installation.
275 <sect1 id="environment-variables">
276 <title>Setting Windows/DOS environment variables</title>
278 Your program might require some environment variable to be set
279 properly in order to run successfully.
280 In this case you need to set this environment variable in the
281 Linux shell, since Wine will pass on the entire shell environment
282 variable settings to the Windows environment variable space.
283 Example for the bash shell (other shells may have a different syntax
286 export MYENVIRONMENTVAR=myenvironmentvarsetting
288 This will make sure your Windows program can access the
289 MYENVIRONMENTVAR environment variable once you start your program
291 If you want to have MYENVIRONMENTVAR set permanently, then you can
292 place the setting into /etc/profile, or also ~/.bashrc in the case of
299 <!-- Keep this comment at the end of the file
302 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
projects / wine / blob