GetCPInfo should return FALSE if called with NULL info buffer.

[wine] / documentation / getting.sgml

  <chapter id="getting-wine">
    <title>Getting Wine</title>
    <sect1 id="installation-methods">
      <title>Wine Installation Methods</title>
      <para>
        Once you've decided that Wine is right for your needs, the next step is 
        to decide how you want to install it.  There are three methods for 
        installing Wine from WineHQ, each with their own advantages and 
        disadvantages.
      </para>

      <sect2 id="installation-methods-package">
        <title>Installation from a package</title>
        <para>
          By far the easiest method for installing Wine is to use a prepackaged 
          version of Wine.  These packages contain ready-to-run Wine binary 
          files specifically compiled for your distribution, and they are 
          tested regularly by the packagers for both functionality and 
          completeness.
        </para>
        <para>
          Packages are the recommended method for installing Wine.  We make 
          them easily available at the 
          <ulink url="http://www.winehq.org/site/download">WineHQ downloads page
          </ulink>, and these are always the latest packages available.  Being 
          popular, Wine packages can also be found elsewhere in official 
          distribution repositories.  These can, however, sometimes be out of 
          date, depending on the distribution.  Packages are easily upgradable 
          as well, and many distributions can upgrade Wine seamlessly with a 
          few clicks.  Building your own installable binary package from a 
          source package is also possible, although it is beyond the scope of 
          this guide.
        </para>
      </sect2>

      <sect2 id="installation-methods-source">
        <title>Installation from a source archive</title>
        <para>
          Sometimes the Wine packages don't fit your needs exactly.  Perhaps 
          they're not available for your architecture or distribution, or 
          perhaps you want to build wine using your own compiler optimizations 
          or with some options disabled, or perhaps you need to modify a 
          specific part of the source code before compilation.  Being an open 
          source project, you are free to do all of these things with Wine's 
          source code, which is provided with every Wine release. This method 
          of installation can be done by downloading a Wine source archive and 
          compiling from the command line.  If you are comfortable with such 
          things and have special needs, this option may be for you.
        </para>
        <para>
          Getting Wine source archives is simple.  Every release, we put a 
          source package in compressed tar.gz format at the 
          <ulink url="http://www.winehq.org/site/download">WineHQ downloads 
          page</ulink>.  Compiling and installing Wine from source is slightly 
          more difficult than using a package, however we will cover it in 
          depth and attempt to hold your hand along the way.
        </para>
      </sect2>

      <sect2 id="installation-methods-cvs">
        <title>Installation from a cvs snapshot</title>
        <para>
          If you wish to try out the bleeding edge of Wine development, or 
          would even like to help develop Wine yourself, you can download the 
          very latest source code from our CVS server.  Instructions for 
          downloading from the Wine cvs repository are available at <ulink 
          url="http://www.winehq.org/site/cvs">http://www.winehq.org/site/cvs
          </ulink>.
        </para>
        <para>
          Please take note that the usual warnings for using a developmental 
          version still apply.  The source code on the CVS server is largely 
          untested and may not even compile properly.  It is, however, the 
          best way to test out how Wine will work in the next version, and if 
          you're modifying source code it's best to get the latest copy.  The 
          CVS repository is also useful for application maintainers interested 
          in testing if an application will still work right for the next 
          release, or if a recent patch actually improves things.  If you're 
          interested in helping us to get an application working in Wine, see 
          the <ulink url="http://www.winehq.org/site/helping-applications">
          guide to helping applications work</ulink>.
        </para>
      </sect2>
    </sect1>

    <sect1 id="installing-wine-package">
      <title>Installing Wine from a package</title>
      <sect2>
        <title>Installing a fresh package</title>
        <para>
          Installing a package on a fresh system is remarkably straightforward. 
          Simply download and install the package using whatever utility your 
          distribution provides.  There is usually no need to explicitly 
          remove old packages before installing, as modern Linux distributions 
          should upgrade and replace them automatically.  If you installed 
          Wine from source code, however, you should remove it before 
          installing a Wine package.  See the section on <link 
          linkend="uninstalling-wine-source">uninstalling Wine from source
          </link> for proper instructions.
        </para>
      </sect2>
      <sect2>
        <title>Different Distributions</title>
        <para>
          Wine works on a huge amount of different Linux distributions, as well 
          other Unix-like systems such as Solaris and FreeBSD, each with their 
          own specific way of installing and managing packages.  Fortunately, 
          however, the same general ideas apply to all of them, and installing 
          Wine should be no more difficult than installing any other software, 
          no matter what distribution you use.  Uninstalling Wine packages is 
          simple as well, and in modern Linux distributions is usually done 
          through the same easy interface as package installation.
        </para>
        <para>
          We won't cover the specifics of installing or uninstalling Wine 
          packages among the various systems' methods of packaging and package 
          management in this guide, however, up to date installation notes for 
          particular distributions can be found at the WineHQ website in the 
          <ulink url="http://www.winehq.org/site/howto">HowTo</ulink>.
          If you need further help figuring 
          out how to simply install a Wine package, we suggest consulting your 
          distribution's documentation, support forums, or IRC channels.
        </para>
      </sect2>
    </sect1>

    <sect1 id="installing-wine-source">
      <title>Installing Wine from source</title>
      <para>
          Before installing Wine from source, make sure you uninstall any Wine 
          binary packages you may have on your system.  Installing from source 
          requires use of the terminal window as well as a full copy of the 
          Wine source code.  Once having downloaded the source from CVS or 
          extracted it from an archive, navigate to it using the terminal and 
          then follow the remaining steps.
      </para>
      <sect2>
        <title>Getting the Build Dependencies</title>
        <para>
          Wine makes use of many open source libraries during its operation.  
          While Wine is not strictly dependent on these libraries and will 
          compile without most of them, much of Wine's functionality is 
          improved by having them available at compile time.  In the past, 
          many user problems were caused by people not having the necessary 
          development libraries when they built Wine from source; because of 
          this reason and others, we highly recommend installing via binary 
          packages or by building source packages which can automatically 
          satisfy their build dependencies.
        </para>
        <para>
          If you wish to install build dependencies by hand, there are several 
          ways to see if you're missing some useful development libraries.  
          The most straightforward approach is to watch the configure program's 
          output before you compile Wine and see if anything important is 
          missing; if it is, simply install what's missing and rerun configure 
          before compiling.  You can also check the file configure generates, 
          (include/config.h.in) and see if what files configure is looking for 
          but not finding.
        </para>
      </sect2>
      <sect2 id="compiling-wine">
        <title>Compiling Wine</title>
        <para>
          Once you've installed the build dependencies you need, you're ready 
          to compile the package.  In the terminal window, after having 
          navigated to the Wine source tree, run the following commands:
            <screen>
            <prompt>$ </><userinput>./configure</>
            <prompt># </><userinput>make depend</>
            <prompt># </><userinput>make</>
            <prompt># </><userinput>make install</>
            </screen>
          The last command requires root privileges.  Although you should 
          never run Wine as root, you will need to install it this way.
        </para>
      </sect2>
      <sect2 id="uninstalling-wine-source">
        <title>Uninstalling Wine from Source</title>
        <para>
          To uninstall Wine from source, once again navigate to the same 
          source folder that you used to install Wine using the terminal.  
          Then, run the following command:
            <screen>
            <prompt># </><userinput>make uninstall</>
            </screen>
          This command will require root privileges, and should remove all of 
          the Wine binary files from your system.  It will not, however, 
          remove your Wine configuration and applications located in your 
          user's home directory, so you are free to install another version of 
          Wine or delete that configuration by hand.
        </para>
      </sect2>
    </sect1>

  </chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-parent-document:("wine-user.sgml" "set" "book" "chapter" "")
End:
-->