2
$PostgreSQL: pgsql/doc/src/sgml/cvs.sgml,v 1.30.4.1 2005-01-22 22:10:09 momjian Exp $
9
<firstname>Marc</firstname>
10
<surname>Fournier</surname>
13
<firstname>Tom</firstname>
14
<surname>Lane</surname>
17
<firstname>Thomas</firstname>
18
<surname>Lockhart</surname>
21
<date>1999-05-20</date>
24
<title>The <productname>CVS</productname> Repository</title>
27
The <productname>PostgreSQL</productname> source code is stored and managed using the
28
<productname>CVS</productname> code management system.
33
anonymous CVS and <productname>CVSup</productname>,
34
are available to pull the <productname>CVS</productname> code tree from the
35
<productname>PostgreSQL</productname> server to your local machine.
39
<title>Getting The Source Via Anonymous <productname>CVS</productname></title>
42
If you would like to keep up with the current sources on a regular
43
basis, you can fetch them from our <productname>CVS</productname> server
44
and then use <productname>CVS</productname> to
45
retrieve updates from time to time.
49
<title>Anonymous CVS</title>
53
You will need a local copy of <productname>CVS</productname>
54
(Concurrent Version Control System), which you can get from
55
<ulink url="http://www.cvshome.org/">http://www.cvshome.org/</ulink>
56
(the official site with the latest version) or any GNU software
57
archive site (often somewhat outdated). We recommend version 1.10
58
or newer. Many systems have a recent version of
59
<application>cvs</application> installed by default.
65
Do an initial login to the <productname>CVS</productname> server:
68
cvs -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot login
71
You will be prompted for a password; you can enter anything except
76
You should only need to do this once, since the password will be
77
saved in <literal>.cvspass</literal> in your home directory.
83
Fetch the <productname>PostgreSQL</productname> sources:
85
cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql
88
This installs the <productname>PostgreSQL</productname> sources into a
89
subdirectory <filename>pgsql</filename>
90
of the directory you are currently in.
94
If you have a fast link to the Internet, you may not need
95
<option>-z3</option>, which instructs
96
<productname>CVS</productname> to use gzip compression for transferred data. But
97
on a modem-speed link, it's a very substantial win.
103
This initial checkout is a little slower than simply downloading
104
a <filename>tar.gz</filename> file; expect it to take 40 minutes or so if you
105
have a 28.8K modem. The advantage of
106
<productname>CVS</productname>
107
doesn't show up until you want to update the file set later on.
113
Whenever you want to update to the latest <productname>CVS</productname> sources,
114
<command>cd</command> into
115
the <filename>pgsql</filename> subdirectory, and issue
117
$ cvs -z3 update -d -P
120
This will fetch only the changes since the last time you updated.
121
You can update in just a couple of minutes, typically, even over
128
You can save yourself some typing by making a file <filename>.cvsrc</filename>
129
in your home directory that contains
136
This supplies the <option>-z3</option> option to all cvs commands, and the
137
<option>-d</option> and <option>-P</option> options to cvs update. Then you just have
143
to update your files.
150
Some older versions of <productname>CVS</productname> have a bug that
151
causes all checked-out files to be stored world-writable in your
152
directory. If you see that this has happened, you can do something like
154
$ chmod -R go-w pgsql
156
to set the permissions properly.
157
This bug is fixed as of
158
<productname>CVS</productname> version 1.9.28.
163
<productname>CVS</productname> can do a lot of other things,
164
such as fetching prior revisions
165
of the <productname>PostgreSQL</productname> sources
166
rather than the latest development version.
167
For more info consult the manual that comes with
168
<productname>CVS</productname>, or see the online
170
<ulink url="http://www.cvshome.org/">http://www.cvshome.org/</ulink>.
174
<sect1 id="cvs-tree">
175
<title><productname>CVS</productname> Tree Organization</title>
179
<title>Author</title>
181
Written by Marc G. Fournier (<email>scrappy@hub.org</email>) on 1998-11-05
187
The command <command>cvs checkout</command> has a flag, <option>-r</option>,
188
that lets you check out a
189
certain revision of a module. This flag makes it easy to, for example,
191
sources that make up release 6_4 of the module `tc' at any time in the
195
$ cvs checkout -r REL6_4 tc
198
This is useful, for instance, if someone claims that there is a bug in
199
that release, but you cannot find the bug in the current working copy.
203
You can also check out a module as it was at any given date using the
204
<option>-D</option> option.
210
When you tag more than one file with the same tag you can think
211
about the tag as <quote>a curve drawn through a matrix of filename vs.
212
revision number</quote>. Say we have 5 files with the following revisions:
215
file1 file2 file3 file4 file5
217
1.1 1.1 1.1 1.1 /--1.1* <-*- TAG
219
1.3 \- 1.3*- 1.3 / 1.3
225
then the tag <literal>TAG</literal> will reference
226
file1-1.2, file2-1.3, etc.
230
For creating a release branch, other than a
231
<literal>-b</> option added to the command, it's the same thing.</para>
236
So, to create the 6.4 release
244
which will create the tag and the branch for the RELEASE tree.
248
For those with <productname>CVS</productname> access, it's simple to
249
create directories for different versions.
250
First, create two subdirectories, RELEASE and CURRENT, so that you don't
251
mix up the two. Then do:
255
cvs checkout -P -r REL6_4 pgsql
257
cvs checkout -P pgsql
260
which results in two directory trees, <filename>RELEASE/pgsql</filename> and
261
<filename>CURRENT/pgsql</filename>. From that point on,
262
<productname>CVS</productname>
263
will keep track of which repository branch is in which directory tree, and will
264
allow independent updates of either tree.
268
If you are <emphasis>only</emphasis> working on the <literal>CURRENT</literal>
269
source tree, you just do
270
everything as before we started tagging release branches.
274
After you've done the initial checkout on a branch
277
$ cvs checkout -r REL6_4
280
anything you do within that directory structure is restricted to that
281
branch. If you apply a patch to that directory structure and do a
287
while inside of it, the patch is applied to the branch and
288
<emphasis>only</emphasis> the branch.
293
<title>Getting The Source Via <productname>CVSup</productname></title>
296
An alternative to using anonymous CVS for retrieving
297
the <productname>PostgreSQL</productname> source tree
298
is <productname>CVSup</productname>.
299
<productname>CVSup</productname> was developed by
300
John Polstra (<email>jdp@polstra.com</email>) to
301
distribute CVS repositories and other file trees for
302
<ulink url="http://www.freebsd.org">the FreeBSD project</ulink>.
306
A major advantage to using
307
<productname>CVSup</productname> is that it can reliably
308
replicate the <emphasis>entire</emphasis> CVS repository on your local system,
309
allowing fast local access to cvs operations such as <option>log</option>
310
and <option>diff</option>. Other advantages include fast synchronization to
311
the <productname>PostgreSQL</productname> server due to an efficient
312
streaming transfer protocol which only sends the changes since the last update.
316
<title>Preparing A <productname>CVSup</productname> Client System</title>
319
Two directory areas are required for <productname>CVSup</productname>
320
to do its job: a local <productname>CVS</productname> repository
321
(or simply a directory area if you are fetching a snapshot rather
322
than a repository; see below)
323
and a local <productname>CVSup</productname> bookkeeping
324
area. These can coexist in the same directory tree.
328
Decide where you want to keep your local copy of the
329
<productname>CVS</productname> repository. On one of our systems we
330
recently set up a repository in <filename>/home/cvs/</filename>,
331
but had formerly kept it under a
332
<productname>PostgreSQL</productname> development tree in
333
<filename>/opt/postgres/cvs/</filename>. If you intend to keep your
334
repository in <filename>/home/cvs/</filename>, then put
337
setenv CVSROOT /home/cvs
340
in your <filename>.cshrc</filename> file, or a similar line in
341
your <filename>.bashrc</filename> or
342
<filename>.profile</filename> file, depending on your shell.
346
The <application>cvs</application> repository area must be initialized.
347
Once <envar>CVSROOT</envar> is set, then this can be done with a
354
after which you should see at least a directory named
355
<filename>CVSROOT</filename> when listing the
356
<envar>CVSROOT</envar> directory:
366
<title>Running a <productname>CVSup</productname> Client</title>
370
<application>cvsup</application> is in your path; on most systems
371
you can do this by typing
378
<application>cvsup</application> using:
381
$ cvsup -L 2 <replaceable class="parameter">postgres.cvsup</replaceable>
384
where <option>-L 2</option> enables some status messages so you
385
can monitor the progress of the update,
386
and <replaceable class="parameter">postgres.cvsup</replaceable> is
387
the path and name you have given to your
388
<productname>CVSup</productname> configuration file.
392
Here is a <productname>CVSup</productname> configuration file
393
modified for a specific installation, and which maintains a full
394
local <productname>CVS</productname> repository:
397
# This file represents the standard CVSup distribution file
398
# for the <productname>PostgreSQL</> ORDBMS project
399
# Modified by lockhart@fourpalms.org 1997-08-28
400
# - Point to my local snapshot source tree
401
# - Pull the full CVS repository, not just the latest snapshot
403
# Defaults that apply to all the collections
404
*default host=cvsup.postgresql.org
407
*default delete use-rel-suffix
408
# enable the following line to get the latest snapshot
410
# enable the following line to get whatever was specified above or by default
411
# at the date specified below
412
#*default date=97.08.29.00.00.00
414
# base directory where CVSup will store its 'bookmarks' file(s)
415
# will create subdirectory sup/
416
#*default base=/opt/postgres # /usr/local/pgsql
417
*default base=/home/cvs
419
# prefix directory where CVSup will store the actual distribution(s)
420
*default prefix=/home/cvs
422
# complete distribution, including all below
425
# individual distributions vs 'the whole thing'
434
If you specify <option>repository</> instead of <option>pgsql</>
435
in the above setup, you will get a complete copy of the entire
436
repository at cvsup.postgresql.org, including its
437
<filename>CVSROOT</filename> directory. If you do that, you will
438
probably want to exclude those files in that directory that you
439
want to modify locally, using a refuse file. For example, for the
440
above setup you might put this in
441
<filename>/home/cvs/sup/repository/refuse</>:
447
See the <productname>CVSup</> manual pages for how to use refuse files.
451
The following is a suggested <productname>CVSup</productname> config file from
452
<ulink url="ftp://ftp.postgresql.org/pub/CVSup/README.cvsup">the <productname>PostgreSQL</> ftp site</ulink>
453
which will fetch the current snapshot only:
456
# This file represents the standard CVSup distribution file
457
# for the <productname>PostgreSQL</> ORDBMS project
459
# Defaults that apply to all the collections
460
*default host=cvsup.postgresql.org
463
*default delete use-rel-suffix
466
# base directory where CVSup will store its 'bookmarks' file(s)
467
*default base=<replaceable class="parameter">/usr/local/pgsql</replaceable>
469
# prefix directory where CVSup will store the actual distribution(s)
470
*default prefix=<replaceable class="parameter">/usr/local/pgsql</replaceable>
472
# complete distribution, including all below
475
# individual distributions vs 'the whole thing'
485
<title>Installing <productname>CVSup</productname></title>
488
<productname>CVSup</productname> is available as source, pre-built
489
binaries, or Linux RPMs. It is far easier to use a binary than to
490
build from source, primarily because the very capable, but
491
voluminous, Modula-3 compiler is required for the build.
495
<title><productname>CVSup</productname> Installation from Binaries</title>
498
You can use pre-built binaries
499
if you have a platform for which binaries
501
<ulink url="ftp://ftp.postgresql.org/pub">the <productname>PostgreSQL</productname> ftp site</ulink>,
502
or if you are running FreeBSD, for which
503
<productname>CVSup</productname> is available as a port.
507
<productname>CVSup</productname> was originally developed as a
508
tool for distributing the <productname>FreeBSD</productname>
509
source tree. It is available as a <quote>port</quote>, and for those running
510
FreeBSD, if this is not sufficient to tell how to obtain and
511
install it then please contribute a procedure here.
517
At the time of writing, binaries are available for
518
Alpha/Tru64, ix86/xBSD,
519
HPPA/HP-UX 10.20, MIPS/IRIX,
520
ix86/linux-libc5, ix86/linux-glibc,
521
Sparc/Solaris, and Sparc/SunOS.
526
Retrieve the binary tar file for
527
<application>cvsup</application>
528
(<application>cvsupd</application> is not required
529
to be a client) appropriate for your platform.
533
<step performance="optional">
535
If you are running FreeBSD, install the <productname>CVSup</productname> port.
539
<step performance="optional">
541
If you have another platform, check for and download the appropriate binary from
542
<ulink url="ftp://ftp.postgresql.org/pub">the <productname>PostgreSQL</productname> ftp site</ulink>.
550
Check the tar file to verify the contents and directory
551
structure, if any. For the linux tar file at least, the static binary
552
and man page is included without any directory packaging.
558
If the binary is in the top level of the tar file, then simply
559
unpack the tar file into your target directory:
563
$ tar zxvf /usr/local/src/cvsup-16.0-linux-i386.tar.gz
564
$ mv cvsup.1 ../doc/man/man1/
571
If there is a directory structure in the tar file, then unpack
572
the tar file within /usr/local/src and move the binaries into
573
the appropriate location as above.
581
Ensure that the new binaries are in your path.
586
$ set path=(<replaceable>path to cvsup</replaceable> $path)
596
<title>Installation from Sources</title>
599
Installing <productname>CVSup</productname> from sources is not
600
entirely trivial, primarily because most systems will need to
601
install a Modula-3 compiler first.
602
This compiler is available as Linux <productname>RPM</productname>,
603
FreeBSD package, or source code.
607
A clean-source installation of Modula-3 takes roughly 200MB of disk space,
608
which shrinks to roughly 50MB of space when the sources are removed.</para>
613
<title>Linux installation</title>
623
Pick up the <productname>Modula-3</productname>
625
<ulink url="http://m3.polymtl.ca/m3">Polytechnique Montr�al</ulink>,
626
who are actively maintaining the code base originally developed by
628
url="http://www.research.digital.com/SRC/modula-3/html/home.html">the DEC Systems Research Center</ulink>.
629
The <productname>PM3</productname> <productname>RPM</productname> distribution is roughly
630
30MB compressed. At the time of writing, the 1.1.10-1 release
631
installed cleanly on RH-5.2, whereas the 1.1.11-1 release is
632
apparently built for another release (RH-6.0?) and does not run on RH-5.2.
636
This particular rpm packaging has
637
<emphasis>many</emphasis> <productname>RPM</productname> files,
638
so you will likely want to place them into a separate
647
Install the Modula-3 rpms:
659
Unpack the cvsup distribution:
663
# tar zxf cvsup-16.0.tar.gz
670
Build the cvsup distribution, suppressing the GUI interface
671
feature to avoid requiring X11 libraries:
674
# make M3FLAGS="-DNOGUI"
677
and if you want to build a static binary to move to systems
678
that may not have Modula-3 installed, try:
681
# make M3FLAGS="-DNOGUI -DSTATIC"
688
Install the built binary:
691
# make M3FLAGS="-DNOGUI -DSTATIC" install
701
> It became clear that I had a problem with my m3 installation; some
702
> X11 libraries were not being found correctly.
704
By the way, you can build the client without the GUI by doing this
705
in the "client" subdirectory:
709
If you build it that way, then it doesn't need the X11 libraries and
710
it's quite a bit smaller. The GUI is fun to watch, but it's not
711
very useful. I originally implemented it because it made debugging
712
the multi-threaded client program much easier.
714
To build a statically-linked client, edit <filename>client/src/m3makefile</filename>
715
to add <literal>build_standalone()</literal>
716
just before the <literal>program()</literal> entry near
724
Then, if cvsup has already been built, remove the machine-specific build directory
725
(e.g. <filename>LINUXELF/</filename>) and rebuild:
730
cp -p LINUXELF/cvsup /usr/local/bin
733
> Anyway, with the reinstall and the two-line patch above (and that
734
> one include-file _POSIX_SOURCE workaround from the previous try),
735
> things built cleanly.
739
> Now I just need a server somewhere to test.
741
If you want to try it out, there are public servers for the FreeBSD
742
source repository at cvsup.freebsd.org and cvsup2.freebsd.org.
743
Here's a suggested supfile:
745
*default host=cvsup.freebsd.org compress
747
*default base=/home/jdp/cvsup-test # FIX THIS
748
*default delete use-rel-suffix
752
This will fetch you the source repository for the programs that get
753
installed into "/bin". I chose it because it's one of the smaller
754
pieces of the system. Make an empty directory someplace for
755
testing, and change the "FIX THIS" line to specify that directory
758
If you are on a T1 or better, you should probably delete the
759
"compress" keyword in the first line.
761
As shown, it will get the repository (RCS) files. If you uncomment
762
the line containing "tag=." then it will instead check out the
763
latest version of each file. There's a bunch more information about
765
<ulink url="http://www.freebsd.org/handbook/cvsup.html">the CVSup Handbook</ulink>.
767
There is one other thing I want to send you, but not tonight. I
768
discovered the hard way that you need a malloc package that is
769
thread-safe with respect to the Modula-3 threads package. The
770
Modula-3 runtime takes care to do the proper mutual exclusion around
771
all calls it makes to malloc. But if you call certain functions in
772
the native C library which in turn call malloc, then the mutual
773
exclusion gets bypassed. This can lead to rare but baffling core
776
For FreeBSD, I solved this by adding a thread-safe malloc package
777
into the Modula-3 runtime. The package is quite portable, and I'm
778
sure it will work well for Linux with very few changes (probably
779
none at all). I want to send it to you along with instructions
780
for making it a part of the "libm3core" library. It's very simple,
781
but I've run out of steam for tonight. :-) Once you have this
782
malloc in place, the CVSup system should be rock solid. We have
783
servers that have been up for weeks and have served many thousands
784
of clients without any observed problems.
786
> We hope to have the PostgreSQL tree using CVSup within a month or
787
> so, and hope to retire sup in September...
789
Great! I'll do my best to help make sure you don't regret it.
795
I'm appending the sources for the thread safe version of malloc that
796
I told you about. I believe that it will simply compile and work
797
under Linux, but I've never had an opportunity to test it there.
798
I urge you to put it into your Modula-3 system; otherwise, you
799
are guaranteed to get occasional mysterious core dumps from cvsupd.
801
As a first step, I'd suggest simply trying to compile it under
806
You shouldn't get any errors or warnings. If you do, contact me
807
before you waste any more time on it.
809
Assuming it compiles OK, copy malloc.c into this directory of your
810
Modula-3 source tree:
812
m3/m3core/src/runtime/LINUXELF
814
In that same directory, edit "m3makefile" and add this line to the
819
Then chdir up into "m3/m3core" of the Modula-3 tree and type
820
"m3build". (I'm assuming you already have a working Modula-3
821
installation.) After that finishes, become root and type "m3ship"
824
That's all there is to it. If you built cvsup and cvsupd to use
825
shared libraries, you don't even need to re-link them. They'll pick
826
up the change automatically from the updated shared library.
828
Let me know if you run into any problems with it.
830
By the way, this is a very good malloc in its own right. It's worth
831
using even aside from the thread safety of it.
836
I've deposited a statically built cvsup client executable (and man pages
837
and test configuration) in
839
/pub/incoming/cvsup-15.1-client-linux.tar.gz
841
This was built and linked on Linux/v2.0.30, RH/v4.2, gnulib/v5.3.12 and
842
includes the thread-safe malloc provided by John Polstra. I'll forward
843
to you the malloc code and an additional installation e-mail from John.
845
The Modula-3 installation takes a good bit of room (~50MB?) and the
846
build environment is unique to Modula-3, but suprisingly enough it
849
The cvsup Makefiles do not work on my machine (they are not portable
850
yet) but each major package (there are 4) can be built without needing
851
the makefiles with two commands each. Not difficult at all. John gives
852
some hints in his e-mail on how to build a static executable, and on how
853
to shrink the size of the executable by leaving out the GUI support.
856
My client test case, picking up a sub-tree of the FreeBSD distribution,
857
worked flawlessly. I haven't tried running a server.
859
Thanks to John for getting me going.
864
For the thread-safe malloc, do the following:
866
2) add the enclosed file "malloc.c" to m3/m3core/src/runtime/LINUXELF
867
3) edit the last line of m3makefile in the same directory to add
869
4) do an "m3build" and an m3ship from the appropriate directory.
871
From what John said, the malloc problem can be noticable for the
872
server-side running cvsupd. Clients may not need it.
874
Unfortunately I seem to have lost John's original good instructions for
875
this, so am doing this from memory. May need to ask John to give
876
instructions again...
883
<!-- Keep this comment at the end of the file
888
sgml-minimize-attributes:nil
889
sgml-always-quote-attributes:t
892
sgml-parent-document:nil
893
sgml-default-dtd-file:"./reference.ced"
894
sgml-exposed-tags:nil
895
sgml-local-catalogs:("/usr/lib/sgml/catalog")
896
sgml-local-ecat-files:nil
added
removed
doc/src/sgml/cvs.sgml
