Make Helvetica Narrow a separate font family.
[wine] / documentation / getting.sgml
1   <chapter id="getting-wine">
2     <title>Getting Wine</title>
3
4     <sect1>
5       <title>The Many Forms of Wine</title>
6       <para>
7         The standard Wine distribution includes quite a few different
8         executables, libraries, and configuration files.  All of these
9         must be set up properly for Wine to work well.  This chapter
10         will guide you through the necessary steps to get Wine
11         installed on your system.
12       </para>
13       <para>
14         If you are running a distribution of Linux that uses packages
15         to keep track of installed software, you may be in luck: A
16         prepackaged version of Wine may already exist for your system.
17         The first three sections will tell you how to find the latest
18         Wine packages and get them installed.  You should be careful,
19         though, about mixing packages between different distributions,
20         and even from different versions of the same distribution.
21         Often a package will only work on the distribution it's
22         compiled for.  We'll cover <link
23         linkend="getting-dist-debian">Debian</link>, <link
24         linkend="getting-dist-redhat">Redhat</link>, and <link
25         linkend="getting-dist-other">other</link> distributions.
26       </para>
27       <para>
28         If you're not lucky enough to have an available package for
29         your operating system, or if you'd prefer a newer version of
30         Wine than already exists as a package, you may have to
31         download the Wine source code and compile it yourself on your
32         own machine.  Don't worry, it's not too hard to do this,
33         especially with the many helpful tools that come with Wine.
34         You don't need any programming experience to compile and
35         install Wine, although it might be nice to have some minor
36         UNIX administrative skill.  We'll cover how to retrieve and
37         compile the official source releases from the <link
38         linkend="getting-source-ftp">FTP archives</link>, and also how
39         to get the cutting edge up-to-the-minute fresh Wine source
40         code from <link linkend="getting-source-cvs">CVS (Concurrent
41         Versions System)</link>.  Both processes of source code
42         installation are similar, and once you master one, you should
43         have no trouble dealing with the other one.
44       </para>
45       <para>
46         Finally, you may someday need to know how to apply a source
47         code patch to your version of Wine.  Perhaps you've uncovered
48         a bug in Wine, reported it to the <ulink
49         url="mailto:wine-devel@winehq.com">Wine mailing list</ulink>,
50         and received a patch from a developer to hopefully fix the
51         bug.  The last section in this chapter will show you how to
52         <link linkend="getting-upgrading">safely apply the
53         patch</link> and revert it if the patch doesn't work.
54       </para>
55     </sect1>
56
57     <sect1 id="getting-dist-debian">
58       <title>Getting Wine for a Debian System</title>
59
60       <para>
61         In most cases on a Debian system, you can install Wine with a
62         single command, as root:
63       </para>
64       <screen>
65 # apt-get install wine
66       </screen>
67       <para>
68         <command>apt-get</command> will connect to a Debian archive
69         across the Internet (thus, you must be online), then download
70         the Wine package and install it on your system.  End of story.
71       </para>
72
73       <para>
74         Of course, Debian's pre-packaged version of Wine may not be the
75         most recent release.  If you are running the stable version of
76         Debian, you may be able to get a slightly newer version of Wine
77         by grabbing the package from the unstable distribution, although
78         this may be a little risky, depending on how far the unstable
79         distribution has diverged from the stable one.  You can find a
80         list of Wine binary packages for the various Debian releases
81         using the
82         <ulink url="http://cgi.debian.org/cgi-bin/search_packages.pl?keywords=wine&amp;searchon=names&amp;version=all&amp;release=all">
83           package search engine</ulink> at <ulink url="http://www.debian.org">
84           www.debian.org</ulink>.
85       </para>
86
87       <para>
88         To install a package that's not part of your distribution, you
89         must use <command>dpkg</command> instead of
90         <command>apt-get</command>.  Since <command>dpkg</command>
91         doesn't download the file for you, you must do it yourself.
92         Follow the link on the package search engine to the desired
93         package, then click on the <guibutton>Go To Download
94           Page</guibutton> button and follow the instructions.  Save the
95         file to your hard drive, then run <command>dpkg</command> on it.
96         For example, if you saved the file to your home directory, you
97         might perform the following actions to install it:
98       </para>
99       <screen>
100 $ su -
101 <emphasis>&lt;Type in root password></emphasis>
102 # cd /home/user
103 # dpkg -i wine_0.0.20000109-3.deb
104     </screen>
105       <para>
106         You may also want to install the
107         <systemitem>wine-doc</systemitem> package, and if you are
108         using Wine from the 2.3 distribution (Woody), the
109         <systemitem>wine-utils</systemitem> package as well.
110       </para>
111     </sect1>
112
113     <sect1 id="getting-dist-redhat">
114       <title>Getting Wine for a Redhat System</title>
115
116       <para>
117         Redhat/RPM users can use <ulink url="http://rpmfind.net/linux/RPM/">
118           rpmfind.net</ulink> to track down available Wine RPM binaries.  
119         <ulink url="http://rpmfind.net/linux/RPM/WByName.html"> This
120           page</ulink> contains a list of all rpmfind packages that start with
121         the letter "W", including a few Wine packages
122       </para>
123
124       <!-- *** Should really flesh this out more!  Any Redhat-running
125       *** volunteers?
126       -->
127
128     </sect1>
129
130     <sect1 id="getting-dist-other">
131       <title>Getting Wine for Other Distributions</title>
132
133       <para>
134         The first place you should look if your system isn't Debian or
135         Redhat is the <ulink
136         url="http://www.winehq.com/download.html">WineHQ Download
137         Page</ulink>.  This page lists many assorted archives of
138         binary (precompiled) Wine files.
139       </para>
140
141       <para>
142         <ulink url="http://ftpsearch.lycos.com/?form=medium">
143           Lycos FTPSearch</ulink> is another useful resource for
144         tracking down miscellaneous distribution packages.
145       </para>
146
147       <!-- *** Add other distributions, e.g., Mandrake, SUSE, Slackware *** -->
148
149     </sect1>
150
151     <sect1 id="getting-source-ftp">
152       <title>Getting Wine Source Code from the FTP Archive</title>
153
154       <para>
155         If the version of Wine you want does not exist in package form,
156         you can download the source code yourself and compile it on your
157         machine.  Although this might seem a little intimidating at
158         first if you've never done it, you'll find that it'll often go
159         quite smoothly, especially on the newer Linux distributions.
160       </para>
161
162       <para>
163         The safest way to grab the source is from one of the official
164         FTP archives.  An up to date listing is in the <ulink
165         url="http://www.winehq.com/source/ANNOUNCE">ANNOUNCE </ulink>
166         file in the Wine distribution (which you would have if you
167         already downloaded it).  Here is a (possibly out of date) list
168         of FTP servers carrying Wine:
169       </para>
170       <itemizedlist>
171         <listitem>
172           <para>
173             <ulink url="ftp://metalab.unc.edu/pub/Linux/ALPHA/wine/development/">
174               ftp://metalab.unc.edu/pub/Linux/ALPHA/wine/development/
175             </ulink>
176           </para>
177         </listitem>
178         <listitem>
179           <para>
180             <ulink url="ftp://tsx-11.mit.edu/pub/linux/ALPHA/Wine/development/">
181               ftp://tsx-11.mit.edu/pub/linux/ALPHA/Wine/development/
182             </ulink>
183           </para>
184         </listitem>
185         <listitem>
186           <para>
187             <ulink url="ftp://ftp.infomagic.com/pub/mirrors/linux/sunsite/ALPHA/wine/development/">
188               ftp://ftp.infomagic.com/pub/mirrors/linux/sunsite/ALPHA/wine/development/
189             </ulink>
190           </para>
191         </listitem>
192         <listitem>
193           <para>
194             <ulink url="ftp://orcus.progsoc.uts.edu.au/pub/Wine/development/">
195               ftp://orcus.progsoc.uts.edu.au/pub/Wine/development/
196             </ulink>
197           </para>
198         </listitem>
199       </itemizedlist>
200       <para>
201         The official releases are tagged by date with the format
202         "Wine-YYYYMMDD.tar.gz".  Your best bet is to grab the latest
203         one.
204       </para>
205       <para>
206         FIXME: Explain how to un-tar, compile, and install Wine from a tarball.
207       </para>
208
209       <para></para>
210     </sect1>
211
212     <sect1 id="getting-source-cvs">
213       <title>Getting Wine Source Code from CVS</title>
214
215       <para>
216         The official web page for Wine CVS is
217         <ulink url="http://www.winehq.com/dev.html">
218           http://www.winehq.com/dev.html</ulink>.
219       </para>
220       <para>
221         First, you need to get a copy of the latest Wine sources
222         using CVS. You can tell it where to find the source tree by
223         setting the <envar>CVSROOT</envar> environment variable. You
224         also have to log in anonymously to the wine CVS server.  In
225         <command>bash</command>, it might look something like this:
226       </para>
227       <screen>
228 $ export CVSROOT=:pserver:cvs@cvs.winehq.com:/home/wine
229 $ cvs login
230 Password: cvs
231 $ cvs checkout wine
232     </screen>
233       <para>
234         That'll pull down the entire Wine source tree from
235         winehq.com and place it in the current directory (actually
236         in the 'wine' subdirectory).  CVS has a million command line
237         parameters, so there are many ways to pull down files, from
238         anywhere in the revision history.  Later, you can grab just
239         the updates:
240       </para>
241       <screen>
242 $ cvs -dP update
243       </screen>
244       <para>
245         <command>cvs update</command> works from inside the source tree.
246         You don't need the <envar>CVSROOT</envar> environment variable
247         to run it either.  You just have to be inside the source tree.
248         The <parameter>-d</parameter> and <parameter>-P</parameter>
249         options make sure your local Wine tree directory structure stays
250         in sync with the remote repository.
251       </para>
252       <para>
253         After you've made changes, you can create a patch with
254         <command>cvs diff -u</command>, which sends output to stdout
255         (the <parameter>-u</parameter> controls the format of the
256         patch). So, to create an <filename>my_patch.diff</filename>
257         file, you would do this:
258       </para>
259       <screen>
260 $ cvs diff -u > my_patch.diff
261       </screen>
262       <para>
263         You can call <command>cvs diff</command> from anywhere in the
264         tree (just like <command>cvs update</command>), and it will
265         always grab recursively from that point.  You can also specify
266         single files or subdirectories:
267       </para>
268       <screen>
269 $ cvs diff -u dlls/winaspi > my_aspi_patch.diff
270       </screen>
271       <para>
272         Experiment around a little.  It's fairly intuitive.
273       </para>
274     </sect1>
275
276     <sect1 id="getting-upgrading">
277       <title>Upgrading Wine with a Patch</title>
278       <para>
279         If you have the Wine source code, as opposed to a binary
280         distribution, you have the option of applying patches to the
281         source tree to fix bugs and add experimental features.
282         Perhaps you've found a bug, reported it to the <ulink
283         url="mailto:wine-devel@winehq.com">Wine mailing list</ulink>,
284         and received a patch file to fix the bug.  You can apply the
285         patch with the <command>patch</command> command, which takes a
286         streamed patch from <filename>stdin</filename>:
287       </para>
288       <screen>
289 $ cd wine
290 $ patch -p0 < ../patch_to_apply.diff
291       </screen>
292       <para>
293         To remove the patch, use the <parameter>-R</parameter> option:
294       </para>
295       <screen>
296 $ patch -p0 -R < ../patch_to_apply.diff
297       </screen>
298       <para>
299         If you want to do a test run to see if the patch will apply
300         successfully (e.g., if the patch was created from an older or
301         newer version of the tree), you can use the
302         <parameter>--dry-run</parameter> parameter to run the patch
303         without writing to any files:
304       </para>
305       <screen>
306 $ patch -p0 --dry-run < ../patch_to_apply.diff
307       </screen>
308       <para>
309         <command>patch</command> is pretty smart about extracting
310         patches from the middle of a file, so if you save an email with
311         an inlined patch to a file on your hard drive, you can invoke
312         patch on it without stripping out the email headers and other
313         text.  <command>patch</command> ignores everything that doesn't
314         look like a patch.
315       </para>
316       <para>
317         FIXME: Go into more depth about the -p0 option...
318       </para>
319     </sect1>
320
321   </chapter>
322
323 <!-- Keep this comment at the end of the file
324 Local variables:
325 mode: sgml
326 sgml-parent-document:("wine-doc.sgml" "set" "book" "chapter" "")
327 End:
328 -->