documentation/cvs.sgml

  <chapter id="cvs">
    <title>Using CVS</title>
    <!-- this part is sort of duplicated in the Wine User Guide's
    getting.sgml file (as a short intro to CVS). Please don't forget 
    to update both!
    -->

    <sect1>
      <title>What is CVS?</title>

      <para>
	<ulink url="http://www.cvshome.org/">CVS</ulink> (Concurrent
	Versions System) is the leading source code control system in
	the freeware community.  It manages source code of projects,
	keeps a history of changes to the source files and improves
	conflict management when two or more developers work on the same
	code part.  Another major benefit of CVS is that it's very easy
	to update a project to the latest version.  CVS features
	flexible branching, intelligent merging, high quality <ulink
	url="http://www.loria.fr/~molli/cvs/doc/cvs_toc.html">documentation</ulink>
	and client/server access with a wide choice of <ulink
	url="http://www.loria.fr/cgi-bin/molli/wilma.cgi/rel">clients</ulink>.
      </para>

      <para>
	Current Wine sources are available via anonymous client/server
	CVS.  You will need CVS 1.9 or above.  If you are coming from
	behind a firewall, you will either need a hole in the firewall
	for the CVS port (2401) or use <ulink
	url="http://www.cyclic.com/cvs/d ev-net.html">SOCKS</ulink>.
      </para>
    </sect1>

    <sect1>
      <title>CVS installation check</title>
      <para>
        First you need to make sure that you have <command>cvs</command>
        installed.
        To check whether this is the case, please run:
      </para>
      <screen>
      <prompt>$ </><userinput>cvs</>
      </screen>
      <para>
	If this was successful, then you should have gotten a nice CVS
	"Usage" help output.  Otherwise (e.g. an error "cvs: command not
	found") you still need to install a CVS package for your
	particular operating system, similar to the instructions given
	in the Wine User Guide chapters for getting and installing a
	Wine package on various systems.
      </para>
    </sect1>

    <sect1>
      <title>Configuring Wine-specific CVS settings</title>

      <para>
        First, you should do a
      </para>
      <screen>
      <prompt>$ </><userinput>touch ~/.cvspass</>
      </screen>
      <para>
        to create or update the file <filename>.cvspass</filename> in
        your home directory, since CVS needs this file (for password
	and login management) and will complain loudly if it doesn't exist.
      </para>

      <para>
        Second, we need to create the file
        <filename>.cvsrc</filename> in your home directory
        containing the CVS configuration settings needed for a valid
        Wine CVS setup (use CVS compression, properly update file and
        directory information, ...).
        The content of this file should look like the following:
        <programlisting>
cvs -z 3
update -PAd
diff -u
checkout -P
        </programlisting>
        Create the file with an editor of your choice, either by running
        <screen>
        <prompt>$ </><userinput>&lt;editor&gt; ~/.cvsrc</>
        </screen>
        , where &lt;editor&gt; is the editor you want to use (e.g.
        <command>joe</command>, <command>ae</command>,
        <command>vi</command>),
        or by creating the file <filename>.cvsrc</filename> in your
        home directory with your favourite graphical editor like nedit, kedit,
        gedit or others.
      </para>
      <para>
	<command>-z</command> sets the compression level (Levels higher
	than 3 will probably not result in faster downloading unless you
	have a fast machine and a slow network connection).
	<command>-Pd</command> will delete empty directories and create
	newly added ones.  <command>-A</command> will reset any previous
	tag in order to get the latest version in the tree.
	<command>-u</command> will create the easiest to read
	patches.  Please do not submit patches with <command>diff -w</command>.
      </para>

    </sect1>

    <sect1>
      <title>Downloading the Wine CVS tree</title>

      <para>
        Once CVS is installed and the Wine specific CVS
        configuration is done, you can now do a login on our CVS
        server and checkout (download) the Wine source code.
        First, let's do the server login:
      </para>
      <screen>
      <prompt>$ </><userinput>cvs -d :pserver:cvs@cvs.winehq.com:/home/wine login</>
      </screen>
      <para>
        If <command>cvs</command> successfully connects to the CVS server,
        then you will get a "CVS password:" prompt.
        Simply enter "cvs" as the password (the password is
        <emphasis>case sensitive</emphasis>: no capital letters!).
	If you want to use one of the mirror servers for Wine CVS
	download, please refer to the section <link
	linkend="cvs-mirrors">Wine CVS mirror servers</link>.
      </para>

      <para>
        After login, we are able to download the Wine source code tree.
        Please make sure that you are in the directory that you want
        to have the Wine source code in (the Wine source code will
        use the subdirectory <filename>wine/</filename> in this
        directory, since the subdirectory is named after the CVS module
        that we want to check out). We assume that your current directory
        might be your user's home directory.
        To download the Wine tree into the subdirectory <filename>wine/</filename>, run:
      </para>
      <screen>
      <prompt>$ </><userinput>cvs -d :pserver:cvs@cvs.winehq.com:/home/wine checkout wine</>
      </screen>
      <para>
        Downloading the CVS tree might take a while (some minutes
        to few hours), depending on your connection speed.
        Once the download is finished, you should keep a note of
        which directory the newly downloaded
        <filename>wine/</filename> directory is in, by running
        <command>pwd</command> (Print Working Directory):
      </para>
      <screen>
      <prompt>$ </><userinput>pwd</>
      </screen>
      <para>
        Later, you will be able to change to this directory by
        running:
      </para>
      <screen>
      <prompt>$ </><userinput>cd <replaceable>&lt;some_dir&gt;</></>
      </screen>
      <para>
        , where &lt;some_dir&gt; is the directory that
        <command>pwd</command> gave you.
        By running
      </para>
      <screen>
      <prompt>$ </><userinput>cd wine</>
      </screen>
      <para>
        , you can now change to the directory of the Wine CVS tree
        you just downloaded.
      </para>
    </sect1>

    <sect1 id="cvs-mirrors">
      <title>Wine CVS mirror servers</title>

      <para>
	Wine's CVS tree is mirrored at several places arround the world
	to make sure that the source is easily accessible. Note that not
	all servers have all repositories available, but all have at
	least the Wine source.
      </para>
      <para>
        CVS access is granted through CVS' "pserver"
        authentication. You should set
        your <command>CVSROOT</command> environment variable to point to one of
        the servers using this format:
      </para>
      <screen>
CVSROOT=:pserver:&lt;Username&gt;@&lt;CVS Server&gt;:&lt;Server root&gt;
      </screen>
      <para>
        Alternatively, you can use the -d parameter of
        <command>cvs</command> instead.
        Substitude the applicable fields from the table below.
      </para>
      <para>
        Just do a traceroute and a ping on all servers below to find out
	which are
	closest to you.
      </para>
      <para>
        <table><title>Wine CVS servers</title>
	  <tgroup cols=3 align="center">
	    <thead>
	      <row>
	        <entry>CVS Server</entry>
		<entry>Username</entry>
		<entry>Password</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
	        <entry>cvs.winehq.com; Minnesota, USA (CodeWeavers)</entry>
		<entry>cvs</entry>
		<entry>cvs</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
      </para>
    </sect1>

    <sect1>
      <title>Other modules available via CVS from WineHQ</title>

      <para>
	The WineHQ CVS server makes a couple of other things available as well.
	To get these, log in anonymously as above and do:
      </para>
      <screen>
      <prompt>$ </><userinput>cvs co <replaceable>&lt;modulename&gt;</></>
      </screen>
      <para>
        where &lt;modulename&gt; is one of:
      </para>
      <itemizedlist>
        <listitem>
	  <para>
            <emphasis>Winehq_com</emphasis> -- source for the WineHQ web site
	  </para>
        </listitem>
        <listitem>
	  <para>
	    <emphasis>c2man</emphasis> -- automatic documentation system, specially modified for Wine
	  </para>
        </listitem>
      </itemizedlist>
    </sect1>

    <sect1>
      <title>Converting a Wine FTP download to a CVS tree</title>

      <para>
        Getting the entire Wine source tree via 
        CVS is pretty slow, especially compared to getting Wine from an
        FTP mirror near you. It's possible to convert a Wine tarball to a CVS
        sandbox, just like you would get by checking out the entire source
        via CVS. Here's how to do it:
      </para>
      <itemizedlist>
        <listitem>
	  <para>
            Get the latest Wine snapshot: Wine-<replaceable>YYMMDD</replaceable>.tar.gz
	  </para>
        </listitem>
        <listitem>
	  <para>
            Get wine-cvsdirs-<replaceable>YYMMDD</replaceable>.tar.gz from <ulink url="ftp://ftp.winehq.com/pub/wine/">ftp://ftp.winehq.com/pub/wine</ulink>
	  </para>
	  <para>
            Use an FTP client rather than a web browser, and be sure to turn off passive mode, otherwise the fetch will hang.
	  </para>
	  <para>
             e.g.:
	  </para>
          <screen>
ftp ftp.winehq.com
cd pub/wine
passive off
ls
          </screen>
        </listitem>
        <listitem>
	  <para>
            Untar them on top of each other:
          </para>
          <screen>
tar xzf Wine-<replaceable>YYYYMMDD</replaceable>.tar.gz
mv wine-<replaceable>YYYYMMDD</replaceable> wine
tar xzf wine-cvsdirs-<replaceable>YYYYMMDD</replaceable>.tar.gz
          </screen>
        </listitem>
        <listitem>
	  <para>
            Update from main tree: login as above, then do
	  </para>
          <screen>
cd wine
cvs update -PAd
          </screen>
        </listitem>
      </itemizedlist>
      <para>
        You will now be completely up to date.
      </para>
    </sect1>

    <sect1>
      <title>WineHQ cvsweb access</title>

      <para>
Direct access to the complete CVS tree is also possible, using Bill Fenner's
<ulink url="http://www.freebsd.org/~fenner/cvsweb/">cvsweb</ulink> package:
        <itemizedlist>
          <listitem>
	    <para>
              <ulink url="http://cvs.winehq.com/cvsweb">cvs.winehq.com/cvsweb</ulink>, on the primary CVS repository
	    </para>
          </listitem>
        </itemizedlist>
      </para>
    </sect1>

  </chapter>

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