1 <chapter id="getting-wine">
2 <title>Getting Wine</title>
4 If you decided that you can use and want to use Wine (e.g. after
5 having read the <link linkend="introduction">introductory
6 chapter</link>), then as a first step you need to find a good
7 compatible Wine version that you like and that works on your
8 system, and after you found one, the next step is to transfer its
9 files to your system somehow.
10 This chapter is here to tell you what you need to take care of
11 in order to successfully accomplish these two steps.
14 <sect1 id="getting-download">
15 <title>How to download Wine?</title>
17 There are three different methods of how the files
18 belonging to Wine may be brought (downloaded) to your system:
22 Getting a single Wine <glossterm>package</glossterm> file
23 (specifically adapted to your particular system), which
24 contains various <glossterm>binary</glossterm> files of Wine
29 Getting a single compressed archive file (usually .tar.gz), which contains
30 all <glossterm>source code</glossterm> files of a standard Wine
36 Downloading from a <glossterm>CVS</glossterm> server,
37 which contains the very latest development source code files
44 <sect2 id="getting-which-wine">
45 <title>Which Wine form should I pick?</title>
48 Now that we told you about the different Wine distribution
49 methods available, let's discuss the advantages and
50 disadvantages of the various methods.
54 <title>Wine distribution methods</title>
56 <term><emphasis>Wine package file</emphasis></term>
60 Intended user level: Beginner to Advanced
64 Using Wine package files is easy for three
66 They install everything else that's needed for their
67 operation, they usually preconfigure a lot, and you
68 don't need to worry about compiling anything or so.
69 However, the Wine Team doesn't have "official" packages.
70 All Wine packages are being offered by external groups,
71 with often slightly inaccurate or quite inaccurate Wine
73 Also, a package you downloaded might turn out to be
74 partially incompatible with your particular system
76 Thus it might actually be <emphasis>better</emphasis>
77 to compile Wine from source and completely install it
78 on your own, by following the instructions in this
84 <term><emphasis>Wine source code via archive file</emphasis></term>
89 Intended user level: Advanced to Expert
93 A Wine source code archive file can be used
94 if you want to compile your own standard Wine release.
95 By using differential patch files to newer Wine versions,
96 you can easily upgrade your outdated Wine directory.
97 However, as you need to manually download patch files
98 and you're only able to download the most current
99 standard Wine release, this is not necessarily the
101 The only advantage a Wine source archive has is that it
102 is a standard Wine release with less development
103 "quirks" than current CVS code. Except for that, CVS
104 source code is much preferred and almost as easy.
109 <term><emphasis>Wine source code via CVS checkout</emphasis></term>
112 Intended user level: Advanced to Expert/Developer
116 The Wine CVS checkout offers the best way to take
117 part in bleeding edge Wine capabilities and
118 development, since you'll be able to download every
119 single CVS commit even <emphasis>beyond</emphasis> the
120 last official Wine release.
121 As upgrading a Wine CVS checkout tree to the latest
122 version is very easy, this is a recommended method
124 Plus, by carefully following the instructions in this
125 Guide, you'll be able to gain the very best Wine
126 environment compatibility (instead of falling victim
127 to package maintainers who fail to follow some
128 instructions in the Wine Packagers Guide).
135 To summarize, the "best" way to install Wine is to download
136 Wine source code via CVS to get the newest code (which might
137 be unstable!). Then you could easily compile and install the
138 Wine files manually. The final configuration part (writing the
139 configuration file and setting up the drive environment) could then
140 be handled by WineSetupTk. All in all the best way to go,
141 except for the about 500MB of disk space that you'll need.
145 With source code archive files, you have the advantage that you're
146 running standard release versions, plus you can update to
147 newer versions via patch files that we release.
148 You won't have the newest code and the flexibility offered by CVS,
153 About binary package files: not sure. There's about a zillion
154 reasons to not like them as much as you'd think: they may be
155 outdated, they may not include "everything", they are
156 <emphasis>not</emphasis> optimized for your particular
157 environment (as opposed to a source compile, which would guess
158 and set everything based on your system), they frequently fail
159 to provide a completely configured Wine environment.
160 On the plus side: they're pretty easy to install and they
161 don't take as much space as a full-blown source code compile.
162 But that's about it when it comes to their advantages.
163 So I'd say they are OK if you want to have a
164 <emphasis>quick</emphasis> way to have a test run of Wine, but
165 for prolonged Wine use, configuring the environment on your
166 own is probably better.
167 Eventually this will change (we'll probably do some packaging
168 efforts on our own at some time), but at the current explosive
169 rate of Wine development, staying as close as possible to the
170 actual Wine development that's going on is the way to go.
174 If you are running a distribution of Linux or some other
175 system that uses packages to keep track of installed software,
176 you should be in luck: A prepackaged version of Wine
177 should already exist for your system.
178 The following sections will tell you how to find the latest
179 Wine packages and get them installed. You should be careful,
180 though, about mixing system packages between different distributions,
181 and even from different versions of the same distribution.
182 Often a package will only work on the distribution which it
183 has been compiled for. We'll cover
184 <link linkend="getting-dist-debian">Debian Linux</link>,
185 <link linkend="getting-dist-linux">Red Hat, Mandrake, SuSE and Slackware Linux</link>,
186 <link linkend="getting-freebsd">FreeBSD</link>, and
187 <link linkend="getting-other">other</link> distributions.
190 If you're not lucky enough to have a package available for
191 your operating system, or if you'd prefer a newer version of
192 Wine than already exists as a package, you will need to
193 download the Wine source code and compile it yourself on your
194 own machine. Don't worry, it's not too hard to do this,
195 especially with the many helpful tools that come with Wine.
196 You don't need any programming experience to compile and
197 install Wine, although it might be nice to have some minor
198 UNIX administrative skills. Working from the source is
199 covered in the Wine Developer's Guide.
200 The main problem with externally maintained package files is
201 that they lack a standard configuration method, and in fact
202 they often fail to configure Wine's Windows environment
203 properly (which is outlined in the Wine Packagers Guide).
209 <sect1 id="getting-wine-package">
210 <title>Getting a Wine package</title>
211 <sect2 id="getting-dist-debian">
212 <title>Debian Linux</title>
215 In most cases on a Debian system (or any other distribution that
216 uses packages that use the file name ending .deb, for that
217 matter), you can download and install Wine with a
218 single command, as <glossterm>root</glossterm>:
221 <prompt># </><userinput>apt-get install wine</>
224 <command>apt-get</command> will connect to a Debian archive
225 across the Internet (thus, you must be online), then download
226 the Wine package and install it on your system. End of story.
227 You might first need to properly update your package setup,
228 though, by using an <glossterm>editor</glossterm> as
229 <glossterm>root</glossterm> to add an entry to
230 <filename>/etc/apt/sources.list</filename> to point to an active
231 package server and then running <command>apt-get
235 Once you're done with that step, you may skip the Wine
236 installation chapter, since apt-get has not only downloaded,
237 but also installed the Wine files already.
238 Thus you can now go directly to the <link
239 linkend="config-wine-main">Configuration section</link>.
243 However, if you don't want to or cannot use the automatic
244 download method for .deb packages that
245 <command>apt-get</command> provides, then please read on.
248 Of course, Debian's pre-packaged version of Wine may not be
249 the most recent release. If you are running the stable
250 version of Debian, you may be able to get a slightly newer
251 version of Wine by grabbing the package from the so-called
252 "unstable" Debian distribution, although this may be a little
253 risky, depending on how far the unstable distribution has
254 diverged from the stable one. You can find a list of Wine
255 binary packages for the various Debian releases using the
256 package search engine at <ulink
257 url="http://www.debian.org">www.debian.org</ulink>.
261 If you downloaded a separate .deb package file (e.g. a newer
262 Wine release as stated above) that's not part of your
263 distribution and thus cannot be installed via
264 <command>apt-get</command>, you must use <command>dpkg</command> instead.
265 For instructions on how to do this, please proceed to the
266 <link linkend="installing">Installation section</link>.
270 <sect2 id="getting-dist-linux">
271 <title>Linux Red Hat, Mandrake, SuSE, and Slackware</title>
274 Red Hat, Mandrake, SuSE and Slackware users can download
275 a wine binary from the
276 <ulink url="http://sourceforge.net/project/showfiles.php?group_id=6241">
277 sourceforge.net Wine download page</ulink>
281 <sect2 id="getting-freebsd">
282 <title>FreeBSD</title>
285 In order to use Wine you need to build and install a new kernel
286 with options USER_LDT, SYSVSHM, SYSVSEM, and SYSVMSG.
290 If you want to install Wine using the FreeBSD port system, run
291 in a <glossterm>terminal</glossterm>:
294 <prompt>$ </><userinput>su -</>
295 <prompt># </><userinput>cd /usr/port/emulators/</>
296 <prompt># </><userinput>make</>
297 <prompt># </><userinput>make install</>
298 <prompt># </><userinput>make clean</>
301 This process will get wine source from the Internet,
302 then download the Wine package and install it on your system.
306 If you want to install Wine from the FreeBSD CD-ROM, run in a
307 <glossterm>terminal</glossterm>:
310 <prompt>$ </><userinput>su -</>
311 <prompt># </><userinput>mount /cdrom</>
312 <prompt># </><userinput>cd /cdrom/packages/All</>
313 <prompt># </><userinput>pkg_add wine_.X.X.X.tgz</>
318 These FreeBSD install instructions completely install the
319 Wine files on your system; you may then proceed to the <link
320 linkend="config-wine-main">Configuration section</link>.
323 You can also download a FreeBSD package of wine from the
324 <ulink url="http://sourceforge.net/project/showfiles.php?group_id=6241">
325 sourceforge.net Wine download page</ulink>
329 <sect2 id="getting-other">
330 <title>Other systems</title>
333 The first place you should look if your system isn't
334 specifically mentioned above is the <ulink
335 url="http://www.winehq.org/download/">WineHQ Download
336 Page</ulink>. This page lists many assorted archives of
337 binary (precompiled) Wine files.
341 You could also try to use
342 <ulink url="http://www.google.com/search?q=wine+package+download">
343 Google</ulink> to track down miscellaneous distribution packages.
347 <!-- *** Add other distributions, e.g., Lindows, Lycoris, Xandros *** -->
351 <sect1 id="getting-wine-source">
352 <title>Getting Wine source code</title>
355 If you are going to compile Wine (instead of installing binary
356 Wine files), either to use the most recent code possible or to
357 improve it, then the first thing to do is to obtain a copy of
358 the source code. We'll cover how to retrieve and compile the
359 official source releases from the <link
360 linkend="getting-source-ftp">FTP archives</link>, and also how
361 to get the cutting edge up-to-the-minute fresh Wine source code
362 from <link linkend="getting-source-cvs">CVS (Concurrent Versions
367 Once you have downloaded Wine source code according to the
368 instructions below, there are two ways to proceed: If you want
369 to manually install and configure Wine, then go to the <link
370 linkend="compiling">Compiling</link> section. If instead you
371 want automatic installation, then go straight to the <link
372 linkend="config-wine-main">Configuration section</link> to make
373 use of <command>wineinstall</command> to automatically install
378 You may also need to know how to apply a source code patch to
379 your version of Wine. Perhaps you've uncovered
380 a bug in Wine, reported it to the
381 <ulink url="http://bugs.winehq.org">Wine Bugzilla</ulink>
383 <ulink url="mailto:wine-devel@winehq.org">Wine mailing list</ulink>,
384 and received a patch from a developer to hopefully fix the
385 bug. We will show you how to
386 <link linkend="getting-upgrading-patch">safely apply the
387 patch</link> and revert it if it doesn't work.
390 <sect2 id="getting-source-ftp">
391 <title>Getting Wine Source Code from an FTP Archive</title>
394 The safest way to grab the source is from one of the official
395 archives. An up to date listing is in the <ulink
396 url="http://www.winehq.org/source/ANNOUNCE">ANNOUNCE</ulink>
397 file in the Wine distribution (which you would have if you
398 already downloaded it). Here is a list
399 of servers carrying Wine:
404 <ulink url="ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/">
405 ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/
411 <ulink url="http://sourceforge.net/project/showfiles.php?group_id=6241&package_id=77449">
412 sourceforge.net download page
418 The official releases are tagged by date with the format
419 "Wine-<replaceable>YYYYMMDD</>.tar.gz". Your best bet is to grab
423 I'd recommend placing the Wine archive file that you chose
424 into the directory where you intend to extract Wine. In this
425 case, let's just assume that it is your home directory.
428 Once you have downloaded a Wine archive file, we need to
429 extract the archive file. This is not very hard to do. First
430 switch to the directory containing the file you just
431 downloaded. Then extract the source in a
432 <glossterm>terminal</glossterm> with (e.g.):
434 <prompt>$ </><userinput>tar xvzf wine-<replaceable>20030115</>.tar.gz</>
438 Just in case you happen to get a Wine archive that uses
439 <filename>.tar.bz2</filename> extension instead of
440 <filename>.tar.gz</filename>:
441 Simply use <command>tar xvjf</command> in that case instead.
444 Since you now have a fully working Wine source tree by
445 having followed the steps above, you're now well-prepared to
446 go to the Wine installation and configuration steps that follow.
450 <sect2 id="getting-source-cvs">
451 <title>Getting Wine Source Code from CVS</title>
452 <!-- this part is sort of duplicated in cvs.sgml
453 (this representation is meant to be a very short intro
454 instead, but it's similar). Please don't forget to update both!
458 This part is intended to be quick and easy, showing the bare minimum
459 of what is needed to download Wine source code via CVS.
460 If you're interested in a very verbose explanation of CVS or
461 advanced CVS topics (configuration settings, CVS mirror servers,
462 other CVS modules on WineHQ, CVSWeb, ...), then please read
463 the full CVS chapter in the Wine Developer's Guide.
467 <title>CVS installation check</title>
469 First you need to make sure that you have <command>cvs</command>
471 To check whether this is the case, please run in a
472 <glossterm>terminal</glossterm>:
475 <prompt>$ </><userinput>cvs</>
478 If this was successful, then you should have gotten a nice CVS
479 "Usage" help output. Otherwise (e.g. an error "cvs: command
480 not found") you still need to install a CVS package for your
481 particular operating system, similar to the instructions given
482 in the chapters for getting and installing a Wine package on
488 <title>Configuring Wine-specific CVS settings</title>
491 First, you should do a
494 <prompt>$ </><userinput>touch ~/.cvspass</>
497 to create or update the file <filename>.cvspass</filename> in
498 your home directory, since CVS needs this file (for password
499 and login management) and will complain loudly if it doesn't exist.
503 Second, we need to create the file
504 <filename>.cvsrc</filename> in your home directory
505 containing the CVS configuration settings needed for a valid
506 Wine CVS setup (use CVS compression, properly update file and
507 directory information, ...).
508 The content of this file should look like the following:
515 Create the file with an <glossterm>editor</glossterm>
516 of your choice, either by running
518 <prompt>$ </><userinput><editor> ~/.cvsrc</>
520 , where <editor> is the editor you want to use (e.g.
521 <command>joe</command>, <command>ae</command>,
522 <command>vi</command>),
523 or by creating the file <filename>.cvsrc</filename> in your
524 home directory with your favorite graphical editor like nedit, kedit,
530 <title>Downloading the Wine CVS tree</title>
533 Once CVS is installed and the Wine specific CVS
534 configuration is done, you can now do a login on our CVS
535 server and checkout (download) the Wine source code.
536 First, let's do the server login, to connect to the US server:
539 <prompt>$ </><userinput>cvs -d :pserver:cvs@cvs.winehq.org:/home/wine login</>
542 To connect to the EU server:
545 <prompt>$ </><userinput>cvs -d :pserver:cvs@rhlx01.fht-esslingen.de:/home/wine login</>
548 If <command>cvs</command> successfully connects to the CVS server,
549 then you will get a "CVS password:" prompt.
550 Simply enter "cvs" as the password (the password is
551 <emphasis>case sensitive</emphasis>: no capital letters!).
555 After login, we are able to download the Wine source code tree.
556 Please make sure that you are in the directory that you want
557 to have the Wine source code in (the Wine source code will
558 use the subdirectory <filename>wine/</filename> in this
559 directory, since the subdirectory is named after the CVS module
560 that we want to check out). We assume that your current directory
561 might be your user's home directory.
562 To download the Wine tree into the subdirectory <filename>wine/</filename>, run,
563 to download from the US server:
566 <prompt>$ </><userinput>cvs -d :pserver:cvs@cvs.winehq.org:/home/wine checkout wine</>
569 Or, to download from the EU server:
572 <prompt>$ </><userinput>cvs -d :pserver:cvs@rhlx01.fht-esslingen.de:/home/wine checkout wine</>
575 Downloading the CVS tree might take a while (some minutes
576 to few hours), depending on your connection speed.
577 Once the download is finished, you should keep a note of
578 which directory the newly downloaded
579 <filename>wine/</filename> directory is in, by running
580 <command>pwd</command> (Print Working Directory):
583 <prompt>$ </><userinput>pwd</>
586 Later, you will be able to change to this directory by
590 <prompt>$ </><userinput>cd <replaceable><some_dir></></>
593 , where <some_dir> is the directory that
594 <command>pwd</command> gave you.
598 <prompt>$ </><userinput>cd wine</>
601 , you can now change to the directory of the Wine CVS tree
602 you just downloaded. Since you now have a fully working Wine
603 source tree by having followed the steps above, you're now
604 well-prepared to go to the Wine installation and configuration
610 <sect2 id="getting-updating-cvs">
611 <title>Updating the Wine CVS tree</title>
614 After a while, you might want to update your Wine CVS tree to
616 Before updating the Wine tree, it might also be a good idea
617 to run <command>make uninstall</command> as root in order to
618 uninstall the installation of the previous Wine version.
621 To proceed with updating Wine, simply <command>cd</command>
622 to the Wine CVS tree directory, then run, if you're using the US server:
625 <prompt>$ </><userinput>make distclean</>
626 <prompt>$ </><userinput>cvs -d :pserver:cvs@cvs.winehq.org:/home/wine update</>
629 or if you're using the EU server:
632 <prompt>$ </><userinput>make distclean</>
633 <prompt>$ </><userinput>cvs -d :pserver:cvs@rhlx01.fht-esslingen.de:/home/wine update</>
636 The <command>make distclean</command> part is optional, but
637 it's a good idea to remove old build and compile configuration
638 files before updating to a newer Wine version. Once the CVS
639 update is finished, you can proceed with installing Wine again
644 <sect2 id="getting-upgrading-patch">
645 <title>Updating Wine with a Patch</title>
647 If you got Wine source code (e.g. via a tar archive file), you
648 have the option of applying patches to the source tree to
649 update to a newer Wine release or to fix bugs and add
650 experimental features. Perhaps you've found a bug, reported
651 it to the <ulink url="mailto:wine-devel@winehq.org">Wine
652 mailing list</>, and received a patch file to fix the bug.
653 You can apply the patch with the <command>patch</> command,
654 which takes a streamed patch from <filename>stdin</>:
656 <prompt>$ </><userinput>cd wine</>
657 <prompt>$ </><userinput>patch -p0 <<replaceable>../patch_to_apply.diff</></>
661 To remove the patch, use the <parameter>-R</> option:
663 <prompt>$ </><userinput>patch -p0 -R <<replaceable>../patch_to_apply.diff</></>
667 If you want to do a test run to see if the patch will apply
668 successfully (e.g., if the patch was created from an older or
669 newer version of the tree), you can use the
670 <parameter>--dry-run</> parameter to run the patch
671 without writing to any files:
673 <prompt>$ </><userinput>patch -p0 --dry-run <<replaceable>../patch_to_apply.diff</></>
677 <command>patch</> is pretty smart about extracting
678 patches from the middle of a file, so if you save an email with
679 an inlined patch to a file on your hard drive, you can invoke
680 patch on it without stripping out the email headers and other
681 text. <command>patch</> ignores everything that doesn't
685 The <parameter>-p0</> option to <command>patch</>
686 tells it to keep the full file name from the patch file. For example,
687 if the file name in the patch file was
688 <filename>wine/programs/clock/main.c</>.
689 Setting the <parameter>-p0</> option would apply the patch
690 to the file of the same name i.e.
691 <filename>wine/programs/clock/main.c </>.
692 Setting the <parameter>-p1</> option would strip off the
693 first part of the file name and apply
694 the patch to <filename>programs/clock/main.c</>.
695 The <parameter>-p1</> option would be useful if you named your
696 top level wine directory differently than the person who sent
697 you the patch. For the <parameter>-p1</> option
698 <command>patch</> should be run from the top level wine
706 <!-- Keep this comment at the end of the file
709 sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")