+++ /dev/null
-<!--
-$PostgreSQL: pgsql/doc/src/sgml/cvs.sgml,v 1.36 2005/11/04 23:13:59 petere Exp $
--->
-
-<appendix id="cvs">
- <appendixinfo>
- <authorgroup>
- <author>
- <firstname>Marc</firstname>
- <surname>Fournier</surname>
- </author>
- <author>
- <firstname>Tom</firstname>
- <surname>Lane</surname>
- </author>
- <author>
- <firstname>Thomas</firstname>
- <surname>Lockhart</surname>
- </author>
- </authorgroup>
- <date>1999-05-20</date>
- </appendixinfo>
-
- <title>The <productname>CVS</productname> Repository</title>
-
- <para>
- The <productname>PostgreSQL</productname> source code is stored and managed using the
- <productname>CVS</productname> code management system.
- </para>
-
- <para>
- At least two methods,
- anonymous CVS and <productname>CVSup</productname>,
- are available to pull the <productname>CVS</productname> code tree from the
- <productname>PostgreSQL</productname> server to your local machine.
- </para>
-
- <sect1 id="anoncvs">
- <title>Getting The Source Via Anonymous <productname>CVS</productname></title>
-
- <para>
- If you would like to keep up with the current sources on a regular
- basis, you can fetch them from our <productname>CVS</productname> server
- and then use <productname>CVS</productname> to
- retrieve updates from time to time.
- </para>
-
- <procedure>
- <title>Anonymous CVS</title>
-
- <step>
- <para>
- You will need a local copy of <productname>CVS</productname>
- (Concurrent Version Control System), which you can get from
- <ulink url="http://www.nongnu.org/cvs/"></ulink>
- (the official site with the latest version) or any GNU software
- archive site (often somewhat outdated). We recommend version 1.10
- or newer. Many systems have a recent version of
- <application>cvs</application> installed by default.
- </para>
- </step>
-
- <step>
- <para>
- Do an initial login to the <productname>CVS</productname> server:
-
-<programlisting>
-cvs -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot login
-</programlisting>
-
- You will be prompted for a password; you can enter anything except
- an empty string.
- </para>
-
- <para>
- You should only need to do this once, since the password will be
- saved in <literal>.cvspass</literal> in your home directory.
- </para>
- </step>
-
- <step>
- <para>
- Fetch the <productname>PostgreSQL</productname> sources:
-<programlisting>
-cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql
-</programlisting>
-
- This installs the <productname>PostgreSQL</productname> sources into a
- subdirectory <filename>pgsql</filename>
- of the directory you are currently in.
-
- <note>
- <para>
- If you have a fast link to the Internet, you may not need
- <option>-z3</option>, which instructs
- <productname>CVS</productname> to use gzip compression for transferred data. But
- on a modem-speed link, it's a very substantial win.
- </para>
- </note>
- </para>
-
- <para>
- This initial checkout is a little slower than simply downloading
- a <filename>tar.gz</filename> file; expect it to take 40 minutes or so if you
- have a 28.8K modem. The advantage of
- <productname>CVS</productname>
- doesn't show up until you want to update the file set later on.
- </para>
- </step>
-
- <step>
- <para>
- Whenever you want to update to the latest <productname>CVS</productname> sources,
- <command>cd</command> into
- the <filename>pgsql</filename> subdirectory, and issue
-<programlisting>
-cvs -z3 update -d -P
-</programlisting>
-
- This will fetch only the changes since the last time you updated.
- You can update in just a couple of minutes, typically, even over
- a modem-speed line.
- </para>
- </step>
-
- <step>
- <para>
- You can save yourself some typing by making a file <filename>.cvsrc</filename>
- in your home directory that contains
-
-<programlisting>
-cvs -z3
-update -d -P
-</programlisting>
-
- This supplies the <option>-z3</option> option to all cvs commands, and the
- <option>-d</option> and <option>-P</option> options to cvs update. Then you just have
- to say
-<programlisting>
-cvs update
-</programlisting>
-
- to update your files.
- </para>
- </step>
- </procedure>
-
- <caution>
- <para>
- Some older versions of <productname>CVS</productname> have a bug that
- causes all checked-out files to be stored world-writable in your
- directory. If you see that this has happened, you can do something like
-<programlisting>
-chmod -R go-w pgsql
-</programlisting>
- to set the permissions properly.
- This bug is fixed as of
- <productname>CVS</productname> version 1.9.28.
- </para>
- </caution>
-
- <para>
- <productname>CVS</productname> can do a lot of other things,
- such as fetching prior revisions
- of the <productname>PostgreSQL</productname> sources
- rather than the latest development version.
- For more info consult the manual that comes with
- <productname>CVS</productname>, or see the online
- documentation at
- <ulink url="http://www.nongnu.org/cvs/"></ulink>.
- </para>
- </sect1>
-
- <sect1 id="cvs-tree">
- <title><productname>CVS</productname> Tree Organization</title>
-
- <para>
- <note>
- <title>Author</title>
- <para>
- Written by Marc G. Fournier (<email>scrappy@hub.org</email>) on 1998-11-05
- </para>
- </note>
- </para>
-
- <para>
- The command <command>cvs checkout</command> has a flag, <option>-r</option>,
- that lets you check out a
- certain revision of a module. This flag makes it easy to, for example,
- retrieve the
- sources that make up release 6_4 of the module `tc' at any time in the
- future:
-
-<programlisting>
-cvs checkout -r REL6_4 tc
-</programlisting>
-
- This is useful, for instance, if someone claims that there is a bug in
- that release, but you cannot find the bug in the current working copy.
-
- <tip>
- <para>
- You can also check out a module as it was at any given date using the
- <option>-D</option> option.
- </para>
- </tip>
- </para>
-
- <para>
- When you tag more than one file with the same tag you can think
- about the tag as <quote>a curve drawn through a matrix of filename vs.
- revision number</quote>. Say we have 5 files with the following revisions:
-
- <programlisting>
- file1 file2 file3 file4 file5
-
- 1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
- 1.2*- 1.2 1.2 -1.2*-
- 1.3 \- 1.3*- 1.3 / 1.3
- 1.4 \ 1.4 / 1.4
- \-1.5*- 1.5
- 1.6
- </programlisting>
-
- then the tag <literal>TAG</literal> will reference
- file1-1.2, file2-1.3, etc.
-
- <note>
- <para>
- For creating a release branch, other than a
- <literal>-b</> option added to the command, it's the same thing.</para>
- </note>
- </para>
-
- <para>
- So, to create the 6.4 release
- I did the following:
-
-<programlisting>
-cd pgsql
-cvs tag -b REL6_4
-</programlisting>
-
- which will create the tag and the branch for the RELEASE tree.
- </para>
-
- <para>
- For those with <productname>CVS</productname> access, it's simple to
- create directories for different versions.
- First, create two subdirectories, RELEASE and CURRENT, so that you don't
- mix up the two. Then do:
-
-<programlisting>
-cd RELEASE
-cvs checkout -P -r REL6_4 pgsql
-cd ../CURRENT
-cvs checkout -P pgsql
-</programlisting>
-
- which results in two directory trees, <filename>RELEASE/pgsql</filename> and
- <filename>CURRENT/pgsql</filename>. From that point on,
- <productname>CVS</productname>
- will keep track of which repository branch is in which directory tree, and will
- allow independent updates of either tree.
- </para>
-
- <para>
- If you are <emphasis>only</emphasis> working on the <literal>CURRENT</literal>
- source tree, you just do
- everything as before we started tagging release branches.
- </para>
-
- <para>
- After you've done the initial checkout on a branch
-
-<programlisting>
-cvs checkout -r REL6_4
-</programlisting>
-
- anything you do within that directory structure is restricted to that
- branch. If you apply a patch to that directory structure and do a
-
-<programlisting>
-cvs commit
-</programlisting>
-
- while inside of it, the patch is applied to the branch and
- <emphasis>only</emphasis> the branch.
- </para>
- </sect1>
-
- <sect1 id="cvsup">
- <title>Getting The Source Via <productname>CVSup</productname></title>
-
- <para>
- An alternative to using anonymous CVS for retrieving
- the <productname>PostgreSQL</productname> source tree
- is <productname>CVSup</productname>.
- <productname>CVSup</productname> was developed by
- John Polstra (<email>jdp@polstra.com</email>) to
- distribute CVS repositories and other file trees for the
- <ulink url="http://www.freebsd.org">FreeBSD project</ulink>.
- </para>
-
- <para>
- A major advantage to using
- <productname>CVSup</productname> is that it can reliably
- replicate the <emphasis>entire</emphasis> CVS repository on your local system,
- allowing fast local access to cvs operations such as <option>log</option>
- and <option>diff</option>. Other advantages include fast synchronization to
- the <productname>PostgreSQL</productname> server due to an efficient
- streaming transfer protocol which only sends the changes since the last update.
- </para>
-
- <sect2>
- <title>Preparing A <productname>CVSup</productname> Client System</title>
-
- <para>
- Two directory areas are required for <productname>CVSup</productname>
- to do its job: a local <productname>CVS</productname> repository
- (or simply a directory area if you are fetching a snapshot rather
- than a repository; see below)
- and a local <productname>CVSup</productname> bookkeeping
- area. These can coexist in the same directory tree.
- </para>
-
- <para>
- Decide where you want to keep your local copy of the
- <productname>CVS</productname> repository. On one of our systems we
- recently set up a repository in <filename>/home/cvs/</filename>,
- but had formerly kept it under a
- <productname>PostgreSQL</productname> development tree in
- <filename>/opt/postgres/cvs/</filename>. If you intend to keep your
- repository in <filename>/home/cvs/</filename>, then put
-
-<programlisting>
-setenv CVSROOT /home/cvs
-</programlisting>
-
- in your <filename>.cshrc</filename> file, or a similar line in
- your <filename>.bashrc</filename> or
- <filename>.profile</filename> file, depending on your shell.
- </para>
-
- <para>
- The <application>cvs</application> repository area must be initialized.
- Once <envar>CVSROOT</envar> is set, then this can be done with a
- single command:
-
-<programlisting>
-cvs init
-</programlisting>
-
- after which you should see at least a directory named
- <filename>CVSROOT</filename> when listing the
- <envar>CVSROOT</envar> directory:
-
-<programlisting>
-$ ls $CVSROOT
-CVSROOT/
-</programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Running a <productname>CVSup</productname> Client</title>
-
- <para>
- Verify that
- <application>cvsup</application> is in your path; on most systems
- you can do this by typing
-
-<programlisting>
-which cvsup
-</programlisting>
-
- Then, simply run
- <application>cvsup</application> using:
-
-<programlisting>
-cvsup -L 2 <replaceable class="parameter">postgres.cvsup</replaceable>
-</programlisting>
-
- where <option>-L 2</option> enables some status messages so you
- can monitor the progress of the update,
- and <replaceable class="parameter">postgres.cvsup</replaceable> is
- the path and name you have given to your
- <productname>CVSup</productname> configuration file.
- </para>
-
- <para>
- Here is a <productname>CVSup</productname> configuration file
- modified for a specific installation, and which maintains a full
- local <productname>CVS</productname> repository:
-
-<programlisting>
-# This file represents the standard CVSup distribution file
-# for the <productname>PostgreSQL</> ORDBMS project
-# Modified by lockhart@fourpalms.org 1997-08-28
-# - Point to my local snapshot source tree
-# - Pull the full CVS repository, not just the latest snapshot
-#
-# Defaults that apply to all the collections
-*default host=cvsup.postgresql.org
-*default compress
-*default release=cvs
-*default delete use-rel-suffix
-# enable the following line to get the latest snapshot
-#*default tag=.
-# enable the following line to get whatever was specified above or by default
-# at the date specified below
-#*default date=97.08.29.00.00.00
-
-# base directory where CVSup will store its 'bookmarks' file(s)
-# will create subdirectory sup/
-#*default base=/opt/postgres # /usr/local/pgsql
-*default base=/home/cvs
-
-# prefix directory where CVSup will store the actual distribution(s)
-*default prefix=/home/cvs
-
-# complete distribution, including all below
-pgsql
-
-# individual distributions vs 'the whole thing'
-# pgsql-doc
-# pgsql-perl5
-# pgsql-src
-</programlisting>
- </para>
-
- <para>
- If you specify <option>repository</> instead of <option>pgsql</>
- in the above setup, you will get a complete copy of the entire
- repository at cvsup.postgresql.org, including its
- <filename>CVSROOT</filename> directory. If you do that, you will
- probably want to exclude those files in that directory that you
- want to modify locally, using a refuse file. For example, for the
- above setup you might put this in
- <filename>/home/cvs/sup/repository/refuse</>:
-<programlisting>
-CVSROOT/config*
-CVSROOT/commitinfo*
-CVSROOT/loginfo*
-</programlisting>
- See the <productname>CVSup</> manual pages for how to use refuse files.
- </para>
-
- <para>
- The following is a suggested <productname>CVSup</productname> config file from
- the <productname>PostgreSQL</>
- <ulink url="ftp://ftp.postgresql.org/pub/CVSup/README.cvsup">
- ftp site</ulink>
- which will fetch the current snapshot only:
-
-<programlisting>
-# This file represents the standard CVSup distribution file
-# for the <productname>PostgreSQL</> ORDBMS project
-#
-# Defaults that apply to all the collections
-*default host=cvsup.postgresql.org
-*default compress
-*default release=cvs
-*default delete use-rel-suffix
-*default tag=.
-
-# base directory where CVSup will store its 'bookmarks' file(s)
-*default base=<replaceable class="parameter">/usr/local/pgsql</replaceable>
-
-# prefix directory where CVSup will store the actual distribution(s)
-*default prefix=<replaceable class="parameter">/usr/local/pgsql</replaceable>
-
-# complete distribution, including all below
-pgsql
-
-# individual distributions vs 'the whole thing'
-# pgsql-doc
-# pgsql-perl5
-# pgsql-src
-</programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Installing <productname>CVSup</productname></title>
-
- <para>
- <productname>CVSup</productname> is available as source, pre-built
- binaries, or Linux RPMs. It is far easier to use a binary than to
- build from source, primarily because the very capable, but
- voluminous, Modula-3 compiler is required for the build.
- </para>
-
- <procedure>
- <title><productname>CVSup</productname> Installation from Binaries</title>
-
- <para>
- You can use pre-built binaries
- if you have a platform for which binaries
- are posted on the <productname>PostgreSQL</productname>
- <ulink url="ftp://ftp.postgresql.org/pub">
- ftp site</ulink>
- or if you are running FreeBSD, for which
- <productname>CVSup</productname> is available as a port.
-
- <note>
- <para>
- <productname>CVSup</productname> was originally developed as a
- tool for distributing the <productname>FreeBSD</productname>
- source tree. It is available as a <quote>port</quote>, and for those running
- FreeBSD, if this is not sufficient to tell how to obtain and
- install it then please contribute a procedure here.
- </para>
- </note>
- </para>
-
- <para>
- At the time of writing, binaries are available for
- Alpha/Tru64, ix86/xBSD,
- HPPA/HP-UX 10.20, MIPS/IRIX,
- ix86/linux-libc5, ix86/linux-glibc,
- Sparc/Solaris, and Sparc/SunOS.
- </para>
-
- <step>
- <para>
- Retrieve the binary tar file for
- <application>cvsup</application>
- (<application>cvsupd</application> is not required
- to be a client) appropriate for your platform.
- </para>
-
- <substeps>
- <step performance="optional">
- <para>
- If you are running FreeBSD, install the <productname>CVSup</productname> port.
- </para>
- </step>
-
- <step performance="optional">
- <para>
- If you have another platform, check for and download the appropriate binary from
- the <productname>PostgreSQL</productname>
- <ulink url="ftp://ftp.postgresql.org/pub">
- ftp site</ulink>.
- </para>
- </step>
- </substeps>
- </step>
-
- <step>
- <para>
- Check the tar file to verify the contents and directory
- structure, if any. For the linux tar file at least, the static binary
- and man page is included without any directory packaging.
- </para>
-
- <substeps>
- <step>
- <para>
- If the binary is in the top level of the tar file, then simply
- unpack the tar file into your target directory:
-
-<programlisting>
-cd /usr/local/bin
-tar zxvf /usr/local/src/cvsup-16.0-linux-i386.tar.gz
-mv cvsup.1 ../doc/man/man1/
-</programlisting>
- </para>
- </step>
-
- <step>
- <para>
- If there is a directory structure in the tar file, then unpack
- the tar file within /usr/local/src and move the binaries into
- the appropriate location as above.
- </para>
- </step>
- </substeps>
- </step>
-
- <step>
- <para>
- Ensure that the new binaries are in your path.
-
-<programlisting>
-$ rehash
-$ which cvsup
-$ set path=(<replaceable>path to cvsup</replaceable> $path)
-$ which cvsup
-/usr/local/bin/cvsup
-</programlisting>
- </para>
- </step>
- </procedure>
- </sect2>
-
- <sect2>
- <title>Installation from Sources</title>
-
- <para>
- Installing <productname>CVSup</productname> from sources is not
- entirely trivial, primarily because most systems will need to
- install a Modula-3 compiler first.
- This compiler is available as Linux <productname>RPM</productname>,
- FreeBSD package, or source code.
-
- <note>
- <para>
- A clean-source installation of Modula-3 takes roughly 200MB of disk space,
- which shrinks to roughly 50MB of space when the sources are removed.</para>
- </note>
- </para>
-
- <procedure>
- <title>Linux installation</title>
-
- <step>
- <para>
- Install Modula-3.
- </para>
-
- <substeps>
- <step>
- <para>
- Pick up the <productname>Modula-3</productname>
- distribution from <ulink url="http://m3.polymtl.ca/m3">
- Polytechnique Montréal</ulink>
- who are actively maintaining the code base originally developed by
- the <ulink url="http://www.research.digital.com/SRC/modula-3/html/home.html">
- DEC Systems Research Center</ulink>.
- The <productname>PM3</productname> <productname>RPM</productname> distribution is roughly
- 30MB compressed. At the time of writing, the 1.1.10-1 release
- installed cleanly on RH-5.2, whereas the 1.1.11-1 release is
- apparently built for another release (RH-6.0?) and does not run on RH-5.2.
-
- <tip>
- <para>
- This particular rpm packaging has
- <emphasis>many</emphasis> <productname>RPM</productname> files,
- so you will likely want to place them into a separate
- directory.
- </para>
- </tip>
- </para>
- </step>
-
- <step>
- <para>
- Install the Modula-3 rpms:
-
-<programlisting>
-# rpm -Uvh pm3*.rpm
-</programlisting>
- </para>
- </step>
- </substeps>
- </step>
-
- <step>
- <para>
- Unpack the cvsup distribution:
-
-<programlisting>
-# cd /usr/local/src
-# tar zxf cvsup-16.0.tar.gz
-</programlisting>
- </para>
- </step>
-
- <step>
- <para>
- Build the cvsup distribution, suppressing the GUI interface
- feature to avoid requiring X11 libraries:
-
-<programlisting>
-# make M3FLAGS="-DNOGUI"
-</programlisting>
-
- and if you want to build a static binary to move to systems
- that may not have Modula-3 installed, try:
-
-<programlisting>
-# make M3FLAGS="-DNOGUI -DSTATIC"
-</programlisting>
- </para>
- </step>
-
- <step>
- <para>
- Install the built binary:
-
-<programlisting>
-# make M3FLAGS="-DNOGUI -DSTATIC" install
-</programlisting>
- </para>
- </step>
- </procedure>
- </sect2>
- </sect1>
-</appendix>
projects / postgresql / commitdiff