Marc Fournier Tom Lane Thomas Lockhart 1999-05-20 The PostgreSQL source code is stored and managed using the CVS code management system. At least two methods, anonymous CVS and CVSup, are available to pull the CVS code tree from the PostgreSQL server to your local machine. If you would like to keep up with the current sources on a regular basis, you can fetch them from our CVS server and then use CVS to retrieve updates from time to time. You will need a local copy of CVS (Concurrent Version Control System), which you can get from (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 cvs installed by default. Do an initial login to the CVS server: cvs -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot login You will be prompted for a password; you can enter anything except an empty string. You should only need to do this once, since the password will be saved in .cvspass in your home directory. Fetch the PostgreSQL sources: cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql This installs the PostgreSQL sources into a subdirectory pgsql of the directory you are currently in. If you have a fast link to the Internet, you may not need -z3, which instructs CVS to use gzip compression for transferred data. But on a modem-speed link, it's a very substantial win. This initial checkout is a little slower than simply downloading a tar.gz file; expect it to take 40 minutes or so if you have a 28.8K modem. The advantage of CVS doesn't show up until you want to update the file set later on. Whenever you want to update to the latest CVS sources, cd into the pgsql subdirectory, and issue $ cvs -z3 update -d -P 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. You can save yourself some typing by making a file .cvsrc in your home directory that contains cvs -z3 update -d -P This supplies the -z3 option to all cvs commands, and the -d and -P options to cvs update. Then you just have to say $ cvs update to update your files. Some older versions of CVS 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 $ chmod -R go-w pgsql to set the permissions properly. This bug is fixed as of CVS version 1.9.28. CVS can do a lot of other things, such as fetching prior revisions of the PostgreSQL sources rather than the latest development version. For more info consult the manual that comes with CVS, or see the online documentation at . Written by Marc G. Fournier (scrappy@hub.org) on 1998-11-05 The command cvs checkout has a flag, -r, 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: $ cvs checkout -r REL6_4 tc 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. You can also check out a module as it was at any given date using the -D option. When you tag more than one file with the same tag you can think about the tag as a curve drawn through a matrix of filename vs. revision number. Say we have 5 files with the following revisions: 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 then the tag TAG will reference file1-1.2, file2-1.3, etc. For creating a release branch, other than a -b option added to the command, it's the same thing. So, to create the 6.4 release I did the following: $ cd pgsql $ cvs tag -b REL6_4 which will create the tag and the branch for the RELEASE tree. For those with CVS 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: cd RELEASE cvs checkout -P -r REL6_4 pgsql cd ../CURRENT cvs checkout -P pgsql which results in two directory trees, RELEASE/pgsql and CURRENT/pgsql. From that point on, CVS will keep track of which repository branch is in which directory tree, and will allow independent updates of either tree. If you are only working on the CURRENT source tree, you just do everything as before we started tagging release branches. After you've done the initial checkout on a branch $ cvs checkout -r REL6_4 anything you do within that directory structure is restricted to that branch. If you apply a patch to that directory structure and do a cvs commit while inside of it, the patch is applied to the branch and only the branch. An alternative to using anonymous CVS for retrieving the PostgreSQL source tree is CVSup. CVSup was developed by John Polstra (jdp@polstra.com) to distribute CVS repositories and other file trees for the FreeBSD project. A major advantage to using CVSup is that it can reliably replicate the entire CVS repository on your local system, allowing fast local access to cvs operations such as log and diff. Other advantages include fast synchronization to the PostgreSQL server due to an efficient streaming transfer protocol which only sends the changes since the last update. Two directory areas are required for CVSup to do its job: a local CVS repository (or simply a directory area if you are fetching a snapshot rather than a repository; see below) and a local CVSup bookkeeping area. These can coexist in the same directory tree. Decide where you want to keep your local copy of the CVS repository. On one of our systems we recently set up a repository in /home/cvs/, but had formerly kept it under a PostgreSQL development tree in /opt/postgres/cvs/. If you intend to keep your repository in /home/cvs/, then put setenv CVSROOT /home/cvs in your .cshrc file, or a similar line in your .bashrc or .profile file, depending on your shell. The cvs repository area must be initialized. Once CVSROOT is set, then this can be done with a single command: $ cvs init after which you should see at least a directory named CVSROOT when listing the CVSROOT directory: $ ls $CVSROOT CVSROOT/ Verify that cvsup is in your path; on most systems you can do this by typing which cvsup Then, simply run cvsup using: $ cvsup -L 2 postgres.cvsup where -L 2 enables some status messages so you can monitor the progress of the update, and postgres.cvsup is the path and name you have given to your CVSup configuration file. Here is a CVSup configuration file modified for a specific installation, and which maintains a full local CVS repository: # This file represents the standard CVSup distribution file # for the 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 If you specify repository instead of pgsql in the above setup, you will get a complete copy of the entire repository at cvsup.postgresql.org, including its CVSROOT 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 /home/cvs/sup/repository/refuse: CVSROOT/config* CVSROOT/commitinfo* CVSROOT/loginfo* See the CVSup manual pages for how to use refuse files. The following is a suggested CVSup config file from the PostgreSQL ftp site which will fetch the current snapshot only: # This file represents the standard CVSup distribution file # for the 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=/usr/local/pgsql # prefix directory where CVSup will store the actual distribution(s) *default prefix=/usr/local/pgsql # complete distribution, including all below pgsql # individual distributions vs 'the whole thing' # pgsql-doc # pgsql-perl5 # pgsql-src CVSup 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. You can use pre-built binaries if you have a platform for which binaries are posted on the PostgreSQL ftp site or if you are running FreeBSD, for which CVSup is available as a port. CVSup was originally developed as a tool for distributing the FreeBSD source tree. It is available as a port, and for those running FreeBSD, if this is not sufficient to tell how to obtain and install it then please contribute a procedure here. 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. Retrieve the binary tar file for cvsup (cvsupd is not required to be a client) appropriate for your platform. If you are running FreeBSD, install the CVSup port. If you have another platform, check for and download the appropriate binary from the PostgreSQL ftp site. 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. If the binary is in the top level of the tar file, then simply unpack the tar file into your target directory: $ cd /usr/local/bin $ tar zxvf /usr/local/src/cvsup-16.0-linux-i386.tar.gz $ mv cvsup.1 ../doc/man/man1/ 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. Ensure that the new binaries are in your path. $ rehash $ which cvsup $ set path=(path to cvsup $path) $ which cvsup /usr/local/bin/cvsup Installing CVSup 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 RPM, FreeBSD package, or source code. 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. Install Modula-3. Pick up the Modula-3 distribution from Polytechnique Montréal who are actively maintaining the code base originally developed by the DEC Systems Research Center. The PM3 RPM 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. This particular rpm packaging has many RPM files, so you will likely want to place them into a separate directory. Install the Modula-3 rpms: # rpm -Uvh pm3*.rpm Unpack the cvsup distribution: # cd /usr/local/src # tar zxf cvsup-16.0.tar.gz Build the cvsup distribution, suppressing the GUI interface feature to avoid requiring X11 libraries: # make M3FLAGS="-DNOGUI" and if you want to build a static binary to move to systems that may not have Modula-3 installed, try: # make M3FLAGS="-DNOGUI -DSTATIC" Install the built binary: # make M3FLAGS="-DNOGUI -DSTATIC" install