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