doc/src/sgml/cvs.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <appendix id="cvs">
   4  <appendixinfo>
   5   <authorgroup>
   6    <author>
   7     <firstname>Marc</firstname>
   8     <surname>Fournier</surname>
   9    </author>
  10    <author>
  11     <firstname>Tom</firstname>
  12     <surname>Lane</surname>
  13    </author>
  14    <author>
  15     <firstname>Thomas</firstname>
  16     <surname>Lockhart</surname>
  17    </author>
  18    <author>
  19     <firstname>David</firstname>
  20     <surname>Fetter</surname>
  21    </author>
  22   </authorgroup>
  23   <date>1999-05-20</date>
  24  </appendixinfo>
  25
  26  <title>The <productname>CVS</productname> Repository</title>
  27
  28  <para>
  29   The <productname>PostgreSQL</productname> source code is stored and managed using the
  30   <productname>CVS</productname> version control system.
  31  </para>
  32
  33  <para>
  34   At least three methods, anonymous CVS, <productname>rsync</productname>,
  35   and <productname>CVSup</productname>,
  36   are available to pull the <productname>CVS</productname> code tree from the
  37   <productname>PostgreSQL</productname> server to your local machine.
  38   Our Wiki, <ulink
  39   url="http://wiki.postgresql.org/index.php/Working_with_CVS"></ulink>,
  40   has additional details on working with CVS.
  41  </para>
  42
  43  <sect1 id="anoncvs">
  44   <title>Getting The Source Via Anonymous <productname>CVS</productname></title>
  45
  46   <para>
  47    If you would like to keep up with the current sources on a regular
  48    basis, you can fetch them from our <productname>CVS</productname> server
  49    and then use <productname>CVS</productname> to
  50    retrieve updates from time to time.
  51   </para>
  52
  53   <procedure>
  54    <title>Anonymous CVS</title>
  55
  56    <step>
  57     <para>
  58      You will need a local copy of <productname>CVS</productname>
  59      (Concurrent Version Control System), which you can get from
  60      <ulink url="http://www.nongnu.org/cvs/"></ulink> (the official
  61      site with the latest version) or any GNU software archive site
  62      (often somewhat outdated). Many systems have a recent version of
  63      <application>cvs</application> installed by default.
  64     </para>
  65    </step>
  66
  67    <step>
  68     <para>
  69      Do an initial login to the <productname>CVS</productname> server:
  70
  71 <programlisting>
  72 cvs -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot login
  73 </programlisting>
  74
  75      You will be prompted for a password; you can enter anything except
  76      an empty string.
  77     </para>
  78
  79     <para>
  80      You should only need to do this once, since the password will be
  81      saved in <filename>.cvspass</filename> in your home directory.
  82     </para>
  83    </step>
  84
  85    <step>
  86     <para>
  87      Fetch the <productname>PostgreSQL</productname> sources:
  88 <programlisting>
  89 cvs -z3 -d :pserver:anoncvs@anoncvs.postgresql.org:/projects/cvsroot co -P pgsql
  90 </programlisting>
  91
  92      This installs the <productname>PostgreSQL</productname> sources into a
  93      subdirectory <filename>pgsql</filename>
  94      of the directory you are currently in.
  95
  96      <note>
  97       <para>
  98        If you have a fast link to the Internet, you might not need
  99        <option>-z3</option>, which instructs
 100        <productname>CVS</productname> to use <command>gzip</command> compression for transferred data.  But
 101        on a modem-speed link, it's a very substantial win.
 102       </para>
 103      </note>
 104     </para>
 105
 106     <para>
 107      This initial checkout is a little slower than simply downloading
 108      a <filename>tar.gz</filename> file; expect it to take 40 minutes or so if you
 109      have a 28.8K modem.  The advantage of
 110      <productname>CVS</productname>
 111      doesn't show up until you want to update the file set later on.
 112     </para>
 113    </step>
 114
 115    <step>
 116     <para>
 117      Whenever you want to update to the latest <productname>CVS</productname> sources,
 118      <command>cd</command> into
 119      the <filename>pgsql</filename> subdirectory, and issue:
 120 <programlisting>
 121 cvs -z3 update -d -P
 122 </programlisting>
 123
 124      This will fetch only the changes since the last time you updated.
 125      You can update in just a couple of minutes, typically, even over
 126      a modem-speed line.
 127     </para>
 128    </step>
 129
 130    <step>
 131     <para>
 132      You can save yourself some typing by making a file <filename>.cvsrc</filename>
 133      in your home directory that contains:
 134
 135 <programlisting>
 136 cvs -z3
 137 update -d -P
 138 </programlisting>
 139
 140      This supplies the <option>-z3</option> option to all <command>cvs</> commands, and the
 141      <option>-d</option> and <option>-P</option> options to <command>cvs update</>.  Then you just have
 142      to say:
 143 <programlisting>
 144 cvs update
 145 </programlisting>
 146
 147      to update your files.
 148     </para>
 149    </step>
 150   </procedure>
 151
 152   <para>
 153    <productname>CVS</productname> can do a lot of other things, such
 154    as fetching prior revisions of the
 155    <productname>PostgreSQL</productname> sources rather than the
 156    latest development version.  For more info consult the manual that
 157    comes with <productname>CVS</productname>, or see the online
 158    documentation at <ulink url="http://www.nongnu.org/cvs/"></ulink>.
 159   </para>
 160   <para>
 161    <productname>CVS</productname> has deficiencies.  For example,
 162    generating diffs that add or remove files requires write access to the
 163    CVS repository.  To work around that deficiency, use
 164    <productname>cvsutils</productname>, which is packaged in several
 165    operating systems, and is available in source form at <ulink
 166    url="http://www.red-bean.com/cvsutils/"></ulink>.
 167   </para>
 168
 169   <para>
 170    Note that building <productname>PostgreSQL</productname> from a CVS
 171    pull requires reasonably up-to-date versions of <application>bison</>
 172    and <application>flex</>, which are not needed to build from a distribution
 173    tarball because the files made with them are pre-built in a tarball.
 174    You will need Perl as well.
 175    Otherwise the tool requirements are the same as building from source.
 176   </para>
 177  </sect1>
 178
 179  <sect1 id="cvs-tree">
 180   <title><productname>CVS</productname> Tree Organization</title>
 181
 182   <para>
 183    <note>
 184     <title>Author</title>
 185     <para>
 186      Written by Marc G. Fournier (<email>scrappy@hub.org</email>) on 1998-11-05
 187     </para>
 188    </note>
 189   </para>
 190
 191   <para>
 192    The command <command>cvs checkout</command> has a flag, <option>-r</option>,
 193    that lets you check out a
 194    certain revision of a module.  This flag makes it easy to, for example,
 195    retrieve the
 196    sources that make up release 6_4 of the module `tc' at any time in the
 197    future:
 198
 199 <programlisting>
 200 cvs checkout -r REL6_4 tc
 201 </programlisting>
 202
 203    This is useful, for instance, if someone claims that there is a bug in
 204    that release, but you cannot find the bug in the current working copy.
 205
 206    <tip>
 207     <para>
 208      You can also check out a module as it was at any given date using the
 209      <option>-D</option> option.
 210     </para>
 211    </tip>
 212   </para>
 213
 214   <para>
 215    When you tag more than one file with the same tag you can think
 216    about the tag as <quote>a curve drawn through a matrix of file name vs.
 217    revision number</quote>.  Say we have 5 files with the following revisions:
 218
 219    <programlisting>
 220              file1   file2   file3   file4   file5
 221
 222              1.1     1.1     1.1     1.1  /--1.1*      &lt;-*-  TAG
 223              1.2*-   1.2     1.2    -1.2*-
 224              1.3  \- 1.3*-   1.3   / 1.3
 225              1.4          \  1.4  /  1.4
 226                            \-1.5*-   1.5
 227                              1.6
 228    </programlisting>
 229
 230    then the tag <literal>TAG</literal> will reference
 231    file1-1.2, file2-1.3, etc.
 232
 233    <note>
 234     <para>
 235      For creating a release branch, other than a
 236      <literal>-b</> option added to the command, it's the same thing.</para>
 237    </note>
 238   </para>
 239
 240   <para>
 241    So, to create the 6.4 release
 242    I did the following:
 243
 244 <programlisting>
 245 cd pgsql
 246 cvs tag -b REL6_4
 247 </programlisting>
 248
 249    which will create the tag and the branch for the RELEASE tree.
 250   </para>
 251
 252   <para>
 253    For those with <productname>CVS</productname> access, it's simple to
 254    create directories for different versions.
 255    First, create two subdirectories, RELEASE and CURRENT, so that you don't
 256    mix up the two.  Then do:
 257
 258 <programlisting>
 259 cd RELEASE
 260 cvs checkout -P -r REL6_4 pgsql
 261 cd ../CURRENT
 262 cvs checkout -P pgsql
 263 </programlisting>
 264
 265    which results in two directory trees, <filename>RELEASE/pgsql</filename> and
 266    <filename>CURRENT/pgsql</filename>. From that point on,
 267    <productname>CVS</productname>
 268    will keep track of which repository branch is in which directory tree, and will
 269    allow independent updates of either tree.
 270   </para>
 271
 272   <para>
 273    If you are <emphasis>only</emphasis> working on the <literal>CURRENT</literal>
 274    source tree, you just do
 275    everything as before we started tagging release branches.
 276   </para>
 277
 278   <para>
 279    After you've done the initial checkout on a branch:
 280
 281 <programlisting>
 282 cvs checkout -r REL6_4
 283 </programlisting>
 284
 285    anything you do within that directory structure is restricted to that
 286    branch.  If you apply a patch to that directory structure and do a:
 287
 288 <programlisting>
 289 cvs commit
 290 </programlisting>
 291
 292    while inside of it, the patch is applied to the branch and
 293    <emphasis>only</emphasis> the branch.
 294   </para>
 295  </sect1>
 296
 297  <sect1 id="rsync">
 298   <title>Getting The Source Via <productname>rsync</productname></title>
 299
 300   <para>
 301    An alternative to using anonymous CVS for retrieving the
 302    <productname>PostgreSQL</productname> source tree is
 303    <productname>rsync</productname>, an incremental file transfer tool.
 304    A major advantage to using <productname>rsync</productname> is that it
 305    can reliably replicate the <emphasis>entire</emphasis> CVS repository
 306    on your local system, allowing fast local access to <command>cvs</>
 307    operations such as <option>log</option> and <option>diff</option>.
 308    Other advantages include fast synchronization to the
 309    <productname>PostgreSQL</productname> server due to an efficient
 310    streaming transfer protocol which only sends the changes since the last
 311    update.
 312   </para>
 313
 314   <para>
 315    You can download the CVS repository using this command:
 316 <programlisting>
 317 rsync -avzH --delete anoncvs.postgresql.org::pgsql-cvs cvsroot/
 318 </programlisting>
 319    For full instructions, see the "rsync" section in the
 320    <ulink url="http://pgfoundry.org/docman/view.php/1000040/4/PGBuildFarm-HOWTO.txt">
 321    pgbuildfarm instructions</ulink>.
 322   </para>
 323  </sect1>
 324
 325  <sect1 id="cvsup">
 326   <title>Getting The Source Via <productname>CVSup</productname></title>
 327
 328   <para>
 329    Another alternative to using anonymous CVS for retrieving
 330    the <productname>PostgreSQL</productname> source tree
 331    is <productname>CVSup</productname>.
 332    <productname>CVSup</productname> was developed by
 333    John Polstra (<email>jdp@polstra.com</email>) to
 334    distribute CVS repositories and other file trees for the
 335    <ulink url="http://www.freebsd.org">FreeBSD project</ulink>.
 336   </para>
 337
 338   <sect2>
 339    <title>Preparing A <productname>CVSup</productname> Client System</title>
 340
 341    <para>
 342     Two directory areas are required for <productname>CVSup</productname>
 343     to do its job: a local <productname>CVS</productname> repository
 344     (or simply a directory area if you are fetching a snapshot rather
 345     than a repository; see below)
 346     and a local <productname>CVSup</productname> bookkeeping
 347     area. These can coexist in the same directory tree.
 348    </para>
 349
 350    <para>
 351     Decide where you want to keep your local copy of the
 352     <productname>CVS</productname> repository. On one of our systems we
 353     recently set up a repository in <filename>/home/cvs/</filename>,
 354     but had formerly kept it under a
 355     <productname>PostgreSQL</productname> development tree in
 356     <filename>/opt/postgres/cvs/</filename>. If you intend to keep your
 357     repository in <filename>/home/cvs/</filename>, then put:
 358
 359 <programlisting>
 360 setenv CVSROOT /home/cvs
 361 </programlisting>
 362
 363     in your <filename>.cshrc</filename> file, or a similar line in
 364     your <filename>.bashrc</filename> or
 365     <filename>.profile</filename> file, depending on your shell.
 366    </para>
 367
 368    <para>
 369     The <application>cvs</application> repository area must be initialized.
 370     Once <envar>CVSROOT</envar> is set, then this can be done with a
 371     single command:
 372
 373 <programlisting>
 374 cvs init
 375 </programlisting>
 376
 377     after which you should see at least a directory named
 378     <filename>CVSROOT</filename> when listing the
 379     <envar>CVSROOT</envar> directory:
 380
 381 <programlisting>
 382 $ ls $CVSROOT
 383 CVSROOT/
 384 </programlisting>
 385    </para>
 386   </sect2>
 387
 388   <sect2>
 389    <title>Running a <productname>CVSup</productname> Client</title>
 390
 391    <para>
 392     Verify that
 393     <application>cvsup</application> is in your path; on most systems
 394     you can do this by typing:
 395
 396 <programlisting>
 397 which cvsup
 398 </programlisting>
 399
 400     Then, simply run
 401     <application>cvsup</application> using:
 402
 403 <programlisting>
 404 cvsup -L 2 <replaceable class="parameter">postgres.cvsup</replaceable>
 405 </programlisting>
 406
 407     where <option>-L 2</option> enables some status messages so you
 408     can monitor the progress of the update,
 409     and <replaceable class="parameter">postgres.cvsup</replaceable> is
 410     the path and name you have given to your
 411     <productname>CVSup</productname> configuration file.
 412    </para>
 413
 414    <para>
 415     Here is a <productname>CVSup</productname> configuration file
 416     modified for a specific installation, and which maintains a full
 417     local <productname>CVS</productname> repository:
 418
 419 <programlisting>
 420 # This file represents the standard CVSup distribution file
 421 # for the <productname>PostgreSQL</> ORDBMS project
 422 # Modified by lockhart@fourpalms.org 1997-08-28
 423 # - Point to my local snapshot source tree
 424 # - Pull the full CVS repository, not just the latest snapshot
 425 #
 426 # Defaults that apply to all the collections
 427 *default host=cvsup.postgresql.org
 428 *default compress
 429 *default release=cvs
 430 *default delete use-rel-suffix
 431 # enable the following line to get the latest snapshot
 432 #*default tag=.
 433 # enable the following line to get whatever was specified above or by default
 434 # at the date specified below
 435 #*default date=97.08.29.00.00.00
 436
 437 # base directory where CVSup will store its 'bookmarks' file(s)
 438 # will create subdirectory sup/
 439 #*default base=/opt/postgres # /usr/local/pgsql
 440 *default base=/home/cvs
 441
 442 # prefix directory where CVSup will store the actual distribution(s)
 443 *default prefix=/home/cvs
 444
 445 # complete distribution, including all below
 446 pgsql
 447
 448 # individual distributions vs 'the whole thing'
 449 # pgsql-doc
 450 # pgsql-perl5
 451 # pgsql-src
 452 </programlisting>
 453    </para>
 454
 455    <para>
 456     If you specify <option>repository</> instead of <option>pgsql</>
 457     in the above setup, you will get a complete copy of the entire
 458     repository at cvsup.postgresql.org, including its
 459     <filename>CVSROOT</filename> directory. If you do that, you will
 460     probably want to exclude those files in that directory that you
 461     want to modify locally, using a refuse file. For example, for the
 462     above setup you might put this in
 463     <filename>/home/cvs/sup/repository/refuse</>:
 464 <programlisting>
 465 CVSROOT/config*
 466 CVSROOT/commitinfo*
 467 CVSROOT/loginfo*
 468 </programlisting>
 469     See the <productname>CVSup</> manual pages for how to use refuse files.
 470    </para>
 471
 472    <para>
 473     The following is a suggested <productname>CVSup</productname> configuration file from
 474     the <productname>PostgreSQL</>
 475     <ulink url="ftp://ftp.postgresql.org/pub/CVSup/README.cvsup">
 476     ftp site</ulink>
 477     which will fetch the current snapshot only:
 478
 479 <programlisting>
 480 # This file represents the standard CVSup distribution file
 481 # for the <productname>PostgreSQL</> ORDBMS project
 482 #
 483 # Defaults that apply to all the collections
 484 *default host=cvsup.postgresql.org
 485 *default compress
 486 *default release=cvs
 487 *default delete use-rel-suffix
 488 *default tag=.
 489
 490 # base directory where CVSup will store its 'bookmarks' file(s)
 491 *default base=<replaceable class="parameter">/usr/local/pgsql</replaceable>
 492
 493 # prefix directory where CVSup will store the actual distribution(s)
 494 *default prefix=<replaceable class="parameter">/usr/local/pgsql</replaceable>
 495
 496 # complete distribution, including all below
 497 pgsql
 498
 499 # individual distributions vs 'the whole thing'
 500 # pgsql-doc
 501 # pgsql-perl5
 502 # pgsql-src
 503 </programlisting>
 504    </para>
 505   </sect2>
 506  </sect1>
 507 </appendix>