documentation/getting.sgml

   1   <chapter id="getting-wine">
   2     <title>Getting Wine</title>
   3     <para>
   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.
  12     </para>
  13
  14     <sect1 id="getting-download">
  15       <title>How to download Wine?</title>
  16       <para>
  17         There are three different methods of how the files
  18         belonging to Wine may be brought (downloaded) to your system:
  19         <itemizedlist>
  20           <listitem>
  21           <para>
  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
  25           </para>
  26           </listitem>
  27           <listitem>
  28           <para>
  29             Getting a single compressed archive file (usually .tar.gz), which contains
  30             all <glossterm>source code</glossterm> files of a standard Wine
  31             release version
  32           </para>
  33           </listitem>
  34           <listitem>
  35           <para>
  36             Downloading from a <glossterm>CVS</glossterm> server,
  37             which contains the very latest development source code files
  38             of Wine
  39           </para>
  40           </listitem>
  41         </itemizedlist>
  42       </para>
  43
  44       <sect2 id="getting-which-wine">
  45         <title>Which Wine form should I pick?</title>
  46
  47         <para>
  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.
  51         </para>
  52
  53         <variablelist>
  54           <title>Wine distribution methods</title>
  55           <varlistentry>
  56             <term><emphasis>Wine package file</emphasis></term>
  57
  58             <listitem>
  59               <para>
  60                 Intended user level: Beginner to Advanced
  61               </para>
  62
  63               <para>
  64                 Using Wine package files is easy for three
  65                 reasons:
  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                 You can get the official wine packages from
  70                 <ulink url="http://sourceforge.net/project/showfiles.php?group_id=6241">
  71           the sourceforge.net Wine download page</ulink>
  72
  73               </para>
  74             </listitem>
  75           </varlistentry>
  76           <varlistentry>
  77             <term><emphasis>Wine source code via archive file</emphasis></term>
  78
  79             <listitem>
  80
  81               <para>
  82                 Intended user level: Advanced to Expert
  83               </para>
  84
  85               <para>
  86                 A Wine source code archive file can be used
  87                 if you want to compile your own standard Wine release.
  88                 By using differential patch files to newer Wine versions,
  89                 you can easily upgrade your outdated Wine directory.
  90                 However, as you need to manually download patch files
  91                 and you're only able to download the most current
  92                 standard Wine release, this is not necessarily the
  93                 best method to use.
  94                 The only advantage a Wine source archive has is that it
  95                 is a standard Wine release with less development
  96                 "quirks" than current CVS code.  Except for that, CVS
  97                 source code is much preferred and almost as easy.
  98               </para>
  99             </listitem>
 100           </varlistentry>
 101           <varlistentry>
 102             <term><emphasis>Wine source code via CVS checkout</emphasis></term>
 103             <listitem>
 104               <para>
 105                 Intended user level: Advanced to Expert/Developer
 106               </para>
 107
 108               <para>
 109                 The Wine CVS checkout offers the best way to take
 110                 part in bleeding edge Wine capabilities and
 111                 development, since you'll be able to download every
 112                 single CVS commit even <emphasis>beyond</emphasis> the
 113                 last official Wine release.
 114                 As upgrading a Wine CVS checkout tree to the latest
 115                 version is very easy, this is a recommended method
 116                 of installing Wine.
 117                 Plus, by carefully following the instructions in this
 118                 Guide, you'll be able to gain the very best Wine
 119                 environment compatibility.
 120               </para>
 121             </listitem>
 122           </varlistentry>
 123         </variablelist>
 124
 125         <para>
 126           If you are running a distribution of Linux or some other
 127           system that uses packages to keep track of installed software,
 128           you should be in luck: A prepackaged version of Wine
 129           should already exist for your system.
 130           The following sections will tell you how to find the latest
 131           Wine packages and get them installed.  You should be careful,
 132           though, about mixing system packages between different distributions,
 133           and even from different versions of the same distribution.
 134           Often a package will only work on the distribution which it
 135           has been compiled for.  We'll cover
 136           <link linkend="getting-dist-debian">Debian Linux</link>,
 137           <link linkend="getting-dist-linux">Red Hat, Mandrake, SUSE and Slackware Linux</link>,
 138           <link linkend="getting-freebsd">FreeBSD</link>, and
 139           <link linkend="getting-other">other</link> distributions.
 140         </para>
 141         <para>
 142           If you're not lucky enough to have a package available for
 143           your operating system, or if you'd prefer a newer version of
 144           Wine than already exists as a package, you will need to
 145           download the Wine source code and compile it yourself on your
 146           own machine.  Don't worry, it's not too hard to do this,
 147           especially with the many helpful tools that come with Wine.
 148           You don't need any programming experience to compile and
 149           install Wine, although it might be nice to have some minor
 150           UNIX administrative skills.  Working from the source is
 151           covered in the Wine Developer's Guide.
 152         </para>
 153       </sect2>
 154
 155     </sect1>
 156
 157     <sect1 id="getting-wine-package">
 158       <title>Getting a Wine package</title>
 159       <sect2 id="getting-dist-debian">
 160         <title>Debian Linux</title>
 161
 162         <para>
 163           In most cases on a Debian system (or any other distribution that
 164         uses packages that use the file name ending .deb, for that
 165         matter), you can download and install Wine with a
 166           single command, as <glossterm>root</glossterm>:
 167         </para>
 168   <screen>
 169   <prompt># </><userinput>apt-get install wine</>
 170   </screen>
 171         <para>
 172           <command>apt-get</command> will connect to a Debian archive
 173           across the Internet (thus, you must be online), then download
 174           the Wine package and install it on your system. End of story.
 175           You might first need to properly update your package setup,
 176           though, by using an <glossterm>editor</glossterm> as
 177           <glossterm>root</glossterm> to add an entry to
 178           <filename>/etc/apt/sources.list</filename> to point to an active
 179           package server and then running <command>apt-get
 180           update</command>.
 181         </para>
 182         <para>
 183           Once you're done with that step, you may skip the Wine
 184           installation chapter, since apt-get has not only downloaded,
 185           but also installed the Wine files already.
 186           Thus you can now go directly to the <link
 187           linkend="config-wine-main">Configuration section</link>.
 188         </para>
 189
 190         <para>
 191           However, if you don't want to or cannot use the automatic
 192           download method for .deb packages that
 193           <command>apt-get</command> provides, then please read on.
 194         </para>
 195         <para>
 196           Of course, Debian's pre-packaged version of Wine may not be
 197           the most recent release.  If you are running the stable
 198           version of Debian, you may be able to get a slightly newer
 199           version of Wine by grabbing the package from the so-called
 200           "unstable" Debian distribution, although this may be a little
 201           risky, depending on how far the unstable distribution has
 202           diverged from the stable one.  You can find a list of Wine
 203           binary packages for the various Debian releases using the
 204           package search engine at <ulink
 205           url="http://www.debian.org">www.debian.org</ulink>.
 206         </para>
 207
 208         <para>
 209           If you downloaded a separate .deb package file (e.g. a newer
 210           Wine release as stated above) that's not part of your
 211           distribution and thus cannot be installed via
 212           <command>apt-get</command>, you must use <command>dpkg</command> instead.
 213           For instructions on how to do this, please proceed to the
 214           <link linkend="installing">Installation section</link>.
 215         </para>
 216       </sect2>
 217
 218       <sect2 id="getting-dist-linux">
 219         <title>Linux Red Hat, Mandrake, SUSE, and Slackware</title>
 220
 221         <para>
 222           Red Hat, Mandrake, SUSE and Slackware users can download
 223           a wine binary from the
 224           <ulink url="http://sourceforge.net/project/showfiles.php?group_id=6241">
 225           sourceforge.net Wine download page</ulink>
 226         </para>
 227       </sect2>
 228
 229       <sect2 id="getting-freebsd">
 230         <title>FreeBSD</title>
 231
 232         <para>
 233         In order to use Wine you need to build and install a new kernel
 234         with options USER_LDT, SYSVSHM, SYSVSEM, and SYSVMSG.
 235         </para>
 236
 237         <para>
 238         If you want to install Wine using the FreeBSD port system, run
 239         in a <glossterm>terminal</glossterm>:
 240         </para>
 241   <screen>
 242   <prompt>$ </><userinput>su -</>
 243   <prompt># </><userinput>cd /usr/ports/emulators/wine/</>
 244   <prompt># </><userinput>make</>
 245   <prompt># </><userinput>make install</>
 246   <prompt># </><userinput>make clean</>
 247   </screen>
 248         <para>
 249           This process will get wine source from the Internet,
 250           then download the Wine package and install it on your system.
 251         </para>
 252
 253         <para>
 254         If you want to install Wine from the FreeBSD CD-ROM, run in a
 255         <glossterm>terminal</glossterm>:
 256         </para>
 257   <screen>
 258   <prompt>$ </><userinput>su -</>
 259   <prompt># </><userinput>mount /cdrom</>
 260   <prompt># </><userinput>cd /cdrom/packages/All</>
 261   <prompt># </><userinput>pkg_add wine_.X.X.X.tgz</>
 262   </screen>
 263          <para>
 264          </para>
 265          <para>
 266            These FreeBSD install instructions completely install the
 267            Wine files on your system; you may then proceed to the <link
 268            linkend="config-wine-main">Configuration section</link>.
 269          </para>
 270          <para>
 271          You can also download a FreeBSD package of wine from the
 272          <ulink url="http://sourceforge.net/project/showfiles.php?group_id=6241">
 273           sourceforge.net Wine download page</ulink>
 274           </para>
 275       </sect2>
 276
 277       <sect2 id="getting-other">
 278         <title>Other systems</title>
 279
 280         <para>
 281           The first place you should look if your system isn't
 282           specifically mentioned above is the <ulink
 283           url="http://www.winehq.org/download/">WineHQ Download
 284           Page</ulink>.  This page lists many assorted archives of
 285           binary (precompiled) Wine files.
 286         </para>
 287
 288         <para>
 289           You could also try to use
 290           <ulink url="http://www.google.com/search?q=wine+package+download">
 291             Google</ulink> to track down miscellaneous distribution packages.
 292         </para>
 293
 294       </sect2>
 295       <!-- *** Add other distributions, e.g., Lindows, Lycoris, Xandros *** -->
 296
 297     </sect1>
 298
 299     <sect1 id="getting-wine-source">
 300       <title>Getting Wine source code</title>
 301
 302       <para>
 303         If you are going to compile Wine (instead of installing binary
 304         Wine files), either to use the most recent code possible or to
 305         improve it, then the first thing to do is to obtain a copy of
 306         the source code. We'll cover how to retrieve and compile the
 307         source releases from the <link
 308         linkend="getting-source">official archives</link>, and also how
 309         to get the cutting edge up-to-the-minute fresh Wine source code
 310         from <link linkend="getting-source-cvs">CVS (Concurrent Versions
 311         System)</link>.
 312       </para>
 313
 314       <para>
 315         Once you have downloaded Wine source code according to the
 316         instructions below, there are two ways to proceed: If you want
 317         to manually install and configure Wine, then go to the <link
 318         linkend="compiling">Compiling</link> section. If instead you
 319         want automatic installation, then go straight to the <link
 320         linkend="config-wine-main">Configuration section</link> to make
 321         use of <command>wineinstall</command> to automatically install
 322         and configure Wine.
 323       </para>
 324
 325       <para>
 326         You may also need to know how to apply a source code patch to
 327         your version of Wine.  Perhaps you've uncovered
 328         a bug in Wine, reported it to the
 329         <ulink url="http://bugs.winehq.org">Wine Bugzilla</ulink>
 330         or the
 331         <ulink url="mailto:wine-devel@winehq.org">Wine mailing list</ulink>,
 332         and received a patch from a developer to hopefully fix the
 333         bug.  We will show you how to
 334         <link linkend="getting-upgrading-patch">safely apply the
 335         patch</link> and revert it if it doesn't work.
 336       </para>
 337
 338       <sect2 id="getting-source">
 339         <title>Getting Wine Source Code from the official archives</title>
 340
 341         <para>
 342           The safest way to grab the source is from one of the official
 343           archives.  An up to date listing is in the <ulink
 344           url="http://www.winehq.org/source/ANNOUNCE">ANNOUNCE</ulink>
 345           file in the Wine distribution (which you would have if you
 346           already downloaded it).  Here is a list
 347           of servers carrying Wine:
 348         </para>
 349         <itemizedlist>
 350           <listitem>
 351             <para>
 352               <ulink url="ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/">
 353                 ftp://ftp.ibiblio.org/pub/Linux/ALPHA/wine/development/
 354               </ulink>
 355             </para>
 356           </listitem>
 357           <listitem>
 358             <para>
 359               <ulink url="http://sourceforge.net/project/showfiles.php?group_id=6241&amp;package_id=77449">
 360                 sourceforge.net download page
 361               </ulink>
 362             </para>
 363           </listitem>
 364         </itemizedlist>
 365         <para>
 366           The official releases are tagged by date with the format
 367           "Wine-<replaceable>YYYYMMDD</>.tar.gz".  Your best bet is to grab
 368           the latest one.
 369         </para>
 370         <para>
 371           I'd recommend placing the Wine archive file that you chose
 372           into the directory where you intend to extract Wine. In this
 373           case, let's just assume that it is your home directory.
 374         </para>
 375         <para>
 376           Once you have downloaded a Wine archive file, we need to
 377           extract the archive file. This is not very hard to do. First
 378           switch to the directory containing the file you just
 379           downloaded. Then extract the source in a
 380           <glossterm>terminal</glossterm> with (e.g.):
 381   <screen>
 382   <prompt>$ </><userinput>tar xvzf wine-<replaceable>20030115</>.tar.gz</>
 383   </screen>
 384         </para>
 385         <para>
 386           Just in case you happen to get a Wine archive that uses
 387           <filename>.tar.bz2</filename> extension instead of
 388           <filename>.tar.gz</filename>:
 389           Simply use <command>tar xvjf</command> in that case instead.
 390         </para>
 391         <para>
 392           Since you now have a fully working Wine source tree by
 393           having followed the steps above, you're now well-prepared to
 394           go to the Wine installation and configuration steps that follow.
 395         </para>
 396       </sect2>
 397
 398       <sect2 id="getting-source-cvs">
 399         <title>Getting Wine Source Code from CVS</title>
 400
 401         <para>
 402           This part is intended to be quick and easy, showing the bare minimum
 403           of what is needed to download Wine source code via CVS.
 404           If you're interested in a very verbose explanation of CVS or
 405           advanced CVS topics (configuration settings, CVS mirror servers,
 406           other CVS modules on WineHQ, CVSWeb, ...), then please read
 407           the full CVS chapter in the Wine Developer's Guide.
 408         </para>
 409
 410         <sect3>
 411           <title>CVS installation check</title>
 412           <para>
 413             First you need to make sure that you have <command>cvs</command>
 414             installed.
 415             To check whether this is the case, please run in a
 416             <glossterm>terminal</glossterm>:
 417           </para>
 418   <screen>
 419   <prompt>$ </><userinput>cvs</>
 420   </screen>
 421           <para>
 422             If this was successful, then you should have gotten a nice CVS
 423             "Usage" help output.  Otherwise (e.g. an error "cvs: command
 424             not found") you still need to install a CVS package for your
 425             particular operating system, similar to the instructions given
 426             in the chapters for getting and installing a Wine package on
 427             various systems.
 428           </para>
 429         </sect3>
 430
 431         <sect3>
 432           <title>Downloading the Wine CVS tree</title>
 433
 434           <para>
 435             Once CVS is installed, you can now do a login on our CVS
 436             server and checkout (download) the Wine source code.
 437             First, let's do the server login, to connect to the US server:
 438           </para>
 439           <screen>
 440   <prompt>$ </><userinput> export CVSROOT=:pserver:cvs@cvs.winehq.org:/home/wine</>
 441   <prompt>$ </><userinput> cvs login</>
 442   </screen>
 443   <para>
 444   To connect to the EU server:
 445   </para>
 446   <screen>
 447   <prompt>$ </><userinput>export CVSROOT=:pserver:cvs@rhlx01.fht-esslingen.de:/home/wine</>
 448   <prompt>$ </><userinput>cvs login</>
 449   </screen>
 450           <para>
 451             If <command>cvs</command> successfully connects to the CVS server,
 452             then you will get a "CVS password:" prompt.
 453             Simply enter "cvs" as the password (the password is
 454             <emphasis>case sensitive</emphasis>: no capital letters!).
 455           </para>
 456
 457           <para>
 458             After login, we are able to download the Wine source code tree.
 459             Please make sure that you are in the directory that you want
 460             to have the Wine source code in (the Wine source code will
 461             use the subdirectory <filename>wine/</filename> in this
 462             directory, since the subdirectory is named after the CVS module
 463             that we want to check out). We assume that your current directory
 464             might be your user's home directory.
 465             To download the Wine tree into the subdirectory <filename>wine/</filename>, run:
 466           </para>
 467   <screen>
 468   <prompt>$ </><userinput> cvs -z3 checkout wine</>
 469   </screen>
 470           <para>
 471             Downloading the CVS tree might take a while (some minutes
 472             to few hours), depending on your connection speed.
 473             Once the download is finished, you should keep a note of
 474             which directory the newly downloaded
 475             <filename>wine/</filename> directory is in, by running
 476             <command>pwd</command> (Print Working Directory):
 477           </para>
 478   <screen>
 479   <prompt>$ </><userinput>pwd</>
 480   </screen>
 481           <para>
 482             Later, you will be able to change to this directory by
 483             running:
 484           </para>
 485   <screen>
 486   <prompt>$ </><userinput>cd <replaceable>&lt;some_dir&gt;</></>
 487   </screen>
 488           <para>
 489             where &lt;some_dir&gt; is the directory that
 490             <command>pwd</command> gave you.
 491             By running
 492           </para>
 493   <screen>
 494   <prompt>$ </><userinput>cd wine</>
 495   </screen>
 496           <para>
 497             you can now change to the directory of the Wine CVS tree
 498             you just downloaded. Since you now have a fully working Wine
 499             source tree by having followed the steps above, you're now
 500             well-prepared to go to the Wine installation and configuration
 501             steps that follow.
 502           </para>
 503         </sect3>
 504       </sect2>
 505
 506       <sect2 id="getting-updating-cvs">
 507         <title>Updating the Wine CVS tree</title>
 508
 509         <para>
 510           After a while, you might want to update your Wine CVS tree to
 511           the current version.
 512           Before updating the Wine tree, it might also be a good idea
 513           to run <command>make uninstall</command> as root in order to
 514           uninstall the installation of the previous Wine version.
 515         </para>
 516         <para>
 517           To proceed with updating Wine, simply <command>cd</command>
 518           to the Wine CVS tree directory, then run, if you're using the US server:
 519         </para>
 520   <screen>
 521   <prompt>$ </><userinput>make distclean</>
 522   <prompt>$ </><userinput>cvs update -PAd</>
 523   </screen>
 524         <para>
 525           The <command>make distclean</command> part is optional, but
 526           it's a good idea to remove old build and compile configuration
 527           files before updating to a newer Wine version.  Once the CVS
 528           update is finished, you can proceed with installing Wine again
 529           as usual.
 530         </para>
 531       </sect2>
 532
 533       <sect2 id="getting-upgrading-patch">
 534         <title>Updating Wine with a Patch</title>
 535         <para>
 536           If you got Wine source code (e.g. via a tar archive file), you
 537           have the option of applying patches to the source tree to
 538           update to a newer Wine release or to fix bugs and add
 539           experimental features.  Perhaps you've found a bug, reported
 540           it to the <ulink url="mailto:wine-devel@winehq.org">Wine
 541           mailing list</>, and received a patch file to fix the bug.
 542           You can apply the patch with the <command>patch</> command,
 543           which takes a streamed patch from <filename>stdin</>:
 544   <screen>
 545   <prompt>$ </><userinput>cd wine</>
 546   <prompt>$ </><userinput>patch -p0 &lt;<replaceable>../patch_to_apply.diff</></>
 547   </screen>
 548         </para>
 549         <para>
 550           To remove the patch, use the <parameter>-R</> option:
 551   <screen>
 552   <prompt>$ </><userinput>patch -p0 -R &lt;<replaceable>../patch_to_apply.diff</></>
 553   </screen>
 554         </para>
 555         <para>
 556           If you want to do a test run to see if the patch will apply
 557           successfully (e.g., if the patch was created from an older or
 558           newer version of the tree), you can use the
 559           <parameter>--dry-run</> parameter to run the patch
 560           without writing to any files:
 561   <screen>
 562   <prompt>$ </><userinput>patch -p0 --dry-run &lt;<replaceable>../patch_to_apply.diff</></>
 563   </screen>
 564         </para>
 565         <para>
 566           <command>patch</> is pretty smart about extracting
 567           patches from the middle of a file, so if you save an email with
 568           an inlined patch to a file on your hard drive, you can invoke
 569           patch on it without stripping out the email headers and other
 570           text.  <command>patch</> ignores everything that doesn't
 571           look like a patch.
 572         </para>
 573         <para>
 574           The <parameter>-p0</> option to <command>patch</>
 575           tells it to keep the full file name from the patch file. For example,
 576           if the file name in the patch file was
 577            <filename>wine/programs/clock/main.c</>.
 578           Setting the <parameter>-p0</> option would apply the patch
 579           to the file of the same name i.e.
 580           <filename>wine/programs/clock/main.c </>.
 581           Setting the <parameter>-p1</> option would strip off the
 582           first part of the file name and apply
 583           the patch to <filename>programs/clock/main.c</>.
 584           The <parameter>-p1</> option would be useful if you named your
 585           top level wine directory differently than the person who sent
 586           you the patch. For the <parameter>-p1</> option
 587           <command>patch</> should be run from the top level wine
 588           directory.
 589         </para>
 590       </sect2>
 591     </sect1>
 592
 593   </chapter>
 594
 595 <!-- Keep this comment at the end of the file
 596 Local variables:
 597 mode: sgml
 598 sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")
 599 End:
 600 -->