File: faq.html

package info (click to toggle)
cvsup 16.1-3
links: PTS
area: main
in suites: potato
size: 2,132 kB
ctags: 166
sloc: modula3: 23,491; ansic: 456; python: 264; makefile: 130; perl: 100; sh: 42; awk: 17
file content (1204 lines) | stat: -rw-r--r-- 44,860 bytes
<html>
<head>
<title>CVSup Frequently Asked Questions</title>
</head>
<body bgcolor="#eddfc8">
<h1 align=center><!--img src="/images/cvsup128.gif" width=444 height=108
  alt="CVSup"-->CVSup</h1>
<h1 align="center">Frequently Asked Questions</h1>
<h2 align="center">John D. Polstra</h2>
<p align="center"><em>Last updated 28 August 1999</em></p>

This is the FAQ for CVSup.  Please send comments and suggestions to
<tt>cvsup-bugs@polstra.com</tt>.
<p>

<h2>Contents</h2>
<ol>
<h3>The Basics</h3>
<li><a href="#whatisit">What is CVSup?</a>
<li><a href="#features">What makes CVSup different from other network
update packages such as rdist and sup?</a>
<li><a href="#filekinds">What kinds of files can be updated using CVSup?</a>
<li><a href="#obtaining">Where can I get CVSup?</a>
<li><a href="#bugreports">Where can I report bugs or ask questions?</a>
<h3>Some Terminology</h3>
<li><a href="#RCS">What is an RCS file?</a>
<li><a href="#CVS">What is a CVS repository?</a>
<h3>Recipes</h3>
<li><a href="#cvsupit">Is there an easy way to get started using CVSup
to update my FreeBSD sources?</a>
<li><a href="#getcurrent">I just want to get the latest version of
the main FreeBSD source tree.  What do I have to do?</a>
<li><a href="#crypto">I want the cryptographic code too.</a>
<li><a href="#caniadopt">When I installed FreeBSD months ago, I
installed the sources too.  Now I want to begin using CVSup to
keep my sources completely up to date.  Do I have to throw out my
existing sources and transfer everything over the network again using
CVSup?</a>
<li><a href="#adopt">But you said above that CVSup won't delete any
files if I don't have a checkouts file.  If I adopt my existing files
as you describe, don't I run a risk that some files which should be
deleted won't be deleted?</a>
<li><a href="#adoptupgrade">How can I adopt my FreeBSD-2.2.5
sources, and update them directly to FreeBSD-current?</a>
<h3>Understanding cvsupfiles</h3>
<li><a href="#default">Which things belong on "*default" lines
in the cvsupfile, and which belong on the lines for individual
collections?</a>
<li><a href="#delete">What does the cvsupfile's "delete" keyword do?</a>
<li><a href="#delnotdflt">If I should always specify "delete", then
why isn't it the default?</a>
<h3>Refuse Files</h3>
<li><a href="#refuse">Help! I can't get "refuse" files to work.</a>
<!--img src="/images/yelnew.gif" width=26 height=12 alt="NEW"-->NEW
<li><a href="#refuse-patterns">How do I specify the patterns in a
refuse file?</a>
<!--img src="/images/yelnew.gif" width=26 height=12 alt="NEW"-->NEW
<li><a href="#refuse-example">How about an example of a refuse file?</a>
<!--img src="/images/yelnew.gif" width=26 height=12 alt="NEW"-->NEW
<li><a href="#refuse-blockfiles">My refuse file works for
directories, but I can't seem to make it block individual files.</a>
<!--img src="/images/yelnew.gif" width=26 height=12 alt="NEW"-->NEW
<li><a href="#refuse-where">Where should I put my refuse files?</a>
<!--img src="/images/yelnew.gif" width=26 height=12 alt="NEW"-->NEW
<li><a href="#refuse-global">Is there a way to create a global
refuse file that will apply to all collections?</a>
<!--img src="/images/yelnew.gif" width=26 height=12 alt="NEW"-->NEW
<h3>CVSup and Firewalls</h3>
<li><a href="#fwtk">How can I make CVSup work through my TIS FWTK
firewall?</a>
<h3>Problems Using CVSup</h3>
<li><a href="#cksum">Why has CVSup suddenly started giving me lots of messages
saying, "Checksum mismatch -- will transfer entire file"?  Every
file gets a "fixup" and that is really slowing down my updates.</a>
<li><a href="#fwhang">When I try to run CVSup, it says it has
connected to the server, but then it just hangs.  What's wrong?</a>
<li><a href="#debugkernel">Whenever I run CVSup under FreeBSD, I get
zillions of messages like this: <tt>fatal process exception: page
fault, fault VA = 0x11a610</tt>.</a>
<li><a href="#bsdos">I tried to run the FreeBSD binary of CVSup under BSD/OS,
but it dumped core right away.  Isn't that supposed to work?</a>
<li><a href="#missingtag">I tried to update my files with CVSup, but
all I got were a bunch of strange looking files whose names all
ended with ",v".  Why?</a>
<h3>Checkouts Files</h3>
<li><a href="#whatarecheckouts">What are these "checkouts" files I
hear about occasionally?</a>
<li><a href="#lostcheckouts">This sounds dangerous.  What if I
accidentally delete one of my checkouts files?</a>
<li><a href="#badcheckouts">What if my checkouts file gets
corrupted somehow?</a>
<li><a href="#extrafiles">Is there anything at all that can go wrong
if I lose a checkouts file?</a>
<h3>Local Modifications in your CVS Repository</h3>
<li><a href="#canilocal">Can I check my own local changes into
a CVS repository that I update with CVSup from a master site?</a>
<li><a href="#nodelete">How can I keep CVSup from deleting the
revisions I have checked in locally?</a>
<li><a href="#revconflicts">How can I keep the revision numbers of my
local check-ins from conflicting with revision numbers originating at
the master site?</a>
<h3>Setting Up a CVSup Server</h3>
<li><a href="#testserver">How can I set up a simple collection to
test the CVSup server?</a>
<li><a href="#serversample">Where can I find a set of CVSup
server configuration files to use as an example?</a>
<h3>Building CVSup from the Sources</h3>
<li><a href="#notc">I've heard lots of horror stories about building
CVSup from the sources.  Why is that?</a>
<li><a href="#fromsource">What steps are involved in building CVSup
from the sources?</a>
<li><a href="#mswin">Has CVSup been ported to Windows 95 or NT?</a>
<h3>Compatibility</h3>
<li><a href="#verscompat">When a new version of CVSup comes
out, do the clients and the server have to be upgraded at the
same time?</a>
<li><a href="#supcompat">Can I use the CVSup client to get updates
from a SUP server?</a>
</ol>

<hr>

<ol>
<h3>The Basics</h3>

<li><a name="whatisit"><em>What is CVSup?</em></a>

<p>CVSup is a software package for transferring and updating
collections of files across a network.  It consists of a server
called <tt>cvsupd</tt> and a client called <tt>cvsup</tt>.

<p>
<li><a name="features"><em>What makes CVSup different from other
network update packages such as rdist and sup?</em></a>

<p>CVSup is faster (often by an order of magnitude) and more
flexible than traditional network update packages.

<p>
<li><a name="filekinds"><em>What kinds of files can be updated
using CVSup?</em></a>

<p>CVSup can efficiently update any kind of file.  It can even
update Unix device nodes, symbolic links, and hard links.  CVSup
supports several different algorithms for updating various kinds of
files.  It tries to use the most efficient method for each file.
For example, <a href="#RCS">RCS</a> files are updated using a
specialized algorithm that takes advantage of their structure to
greatly reduce the update time.  Log files (which are changed only
by appending new text at the end) are likewise updated by a special
algorithm that transmits only the new text.  Other text and binary
files can be updated efficiently by the
<a href="http://samba.anu.edu.au/rsync/">rsync</a> algorithm, which
is built into CVSup.

<p>
<li><a name="obtaining"><em>Where can I get CVSup?</em></a>

<p>CVSup is free software, distributed under a BSD-style license.
You can obtain CVSup from
<a href="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/">
ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/</a>,
and from FreeBSD's
<a href="http://www.freebsd.org/handbook/mirrors-ftp.html">FTP mirror
sites</a> all over the world.

<p>The <a href="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/sources/">
sources</a> subdirectory contains the full sources for CVSup.  Be sure
to read <a href="#compiling">this</a> before fetching the source
distribution.

<p>The <a href="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/binaries/">
binaries</a> subdirectory contains precompiled statically-linked
executables for various platforms:

<p>
<ul>
<li>BSD/OS-ix86
<li>Digital Unix 4.0d
<li>FreeBSD-Alpha
<li>FreeBSD-ix86
<li>Linux-ix86-libc5
<li>Linux-ix86-libc6
<li>NetBSD-ix86
<li>OpenBSD-ix86
<li>Solaris-2-Sparc
<li>SunOS-4-Sparc
</ul>

<p>Be sure to read the appropriate README file for your target
platform.

<p>
<li><a name="bugreports"><em>Where can I report bugs or ask questions?</em></a>

<p>Please address all mail regarding CVSup to
<tt>cvsup-bugs@polstra.com</tt>.

<p>
<h3>Some Terminology</h3>

<li><a name="RCS"><em>What is an RCS file?</em></a>

<p>An RCS file stores many versions of a single source file, all in
one place.  During the lifetime of a project, its source files evolve.
Each source file starts with an initial version.  Over time, changes
are made to the source files to fix bugs and add features.  At key
moments, a programmer wish to save the current version of a source
file.  He can do this by checking it into its corresponding RCS file.
From a given RCS file, one can later extract any desired version of
the source file.  This makes it easy to undo changes that turned out
to be ill-advised, or to recreate an earlier release of the
software.

<p>
<li><a name="CVS"><em>What is a CVS repository?</em></a>

<p>A CVS repository is a collection of RCS files that are managed
together.  For example, the RCS files for all of the sources in a
project would typically be stored together in a CVS repository.

<p>
<h3>Recipes</h3>

<p>
<li><a name="cvsupit"><em>Is there an easy way to get started using
CVSup to update my FreeBSD sources?</em></a>

<p>
Yes, try Jordan Hubbard's "cvsupit" package.  You'll find it
at <a href="ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupit.tgz">
ftp://ftp.freebsd.org/pub/FreeBSD/CVSup/cvsupit.tgz</a>.

<p>
<li><a name="getcurrent"><em>I just want to get the latest version of
the main FreeBSD source tree.  What do I have to do?</em></a>

<p>Make a cvsupfile that looks something like this:

<pre>
    *default host=cvsup3.freebsd.org
    *default base=/usr
    *default prefix=/usr
    *default release=cvs
    *default delete use-rel-suffix
    *default tag=.
    src-all
</pre>

<p>This cvsupfile will create a directory tree "/usr/src" and populate
it with all of the main FreeBSD sources except the export-restricted
cryptographic code.  It will also create a tree "/usr/sup" containing
the <a href="#checkouts">checkouts</a> files that CVSup uses to
maintain state between updates.  If you want your source tree to be
somewhere other than "/usr/src", change the "prefix=" clause.  If
you want the checkouts files to be located somewhere other than
"/usr/sup", change the "base=" clause.

<p>Be sure not to leave out the "tag=." clause.  That tells CVSup to
use checkout mode to send you the most recent version of each source
file.

<p>
<li><a name="crypto"><em>I want the cryptographic code too.</em></a>

<p>
Simply add one more line to the end of the cvsupfile above:

<pre>
    cvs-crypto
</pre>

<p><strong>Note: </strong>If you are located outside of North America,
then you <strong>must</strong> also change the "host=" clause to
specify a non-North American server.  For example:

<pre>
    *default host=cvsup.internat.freebsd.org
</pre>

See <a href="http://www.freebsd.org/handbook/mirrors.html">here</a>
for a complete list of public CVSup servers carrying the FreeBSD
sources.

<p>
<li><a name="caniadopt"><em>When I installed FreeBSD months ago,
I installed the sources too.  Now I want to begin using CVSup to
keep my sources completely up to date.  Do I have to throw out my
existing sources and transfer everything over the network again using
CVSup?</em></a>

<p>No, you don't.  CVSup is capable of "adopting" your existing
sources and bringing them up to date.  If you think about it, your
situation is the same as if you had been updating with CVSup all
along but had lost your checkouts files.  And CVSup uses the same
technique to deal with both situations.  It uses checksums to
determine which revisions of the files you have currently, and then
updates them in the appropriate ways to transform them into the
latest versions.

<p>Look <a href="#adopt">here</a> for the safest way to do this.

<p>
<li><a name="adopt"><em>But you said above that CVSup won't delete any
files if I don't have a checkouts file.  If I adopt my existing files
as you describe, don't I run a risk that some files which should be
deleted won't be deleted?</em></a>

<p>Yes, you do.  The greater the distance between the revisions
you have and the revisions you want to get, the greater the chance
that you'll miss some important file deletions.  Luckily, if you
know approximately or exactly which versions of the files you are
starting with, you can reduce or eliminate this risk.  You do this by
updating twice.  First, you tell CVSup to "update" you to the versions
that you already have.  This won't change any of your files, but it
will create a checkouts file that precisely reflects what you have
currently.  Second, you update again, this time telling CVSup which
version you really want.  On the second update, CVSup will have all
the information it needs in order to know which files to delete.

<p>This is a little tricky and there are a couple of important details we
haven't mentioned yet.  So we'd better give you an example.  Suppose
you installed FreeBSD-2.2.5, including sources, from the CD-ROM.  Now
you decide you want to use CVSup to track the 2.2-stable sources.
For your first update only, use a cvsupfile like this:

<pre>
    *default host=cvsup2.freebsd.org
    *default base=/usr
    *default prefix=/usr
    *default release=cvs
    *default delete use-rel-suffix
    src-all tag=RELENG_2_2_5_RELEASE list=cvs:RELENG_2_2
</pre>

<p>For subsequent updates, change the last line to:

<pre>
    src-all tag=RELENG_2_2
</pre>

<p>The unmentioned details are in this last line.  First of all, how
do you know what to use for the tag?  The answer is, you have to
consult a list.  See the "Configuration" section of the CVSup chapter
in the <a href="http://www.freebsd.org/handbook/cvsup.html">FreeBSD
Handbook</a> for a list of tags that are valid for the FreeBSD
sources.  The important point is that the tag for your first update
should correspond to the version of the sources that you already have.
And the tag for your second and subsequent updates should correspond
to the version of the sources that you want to receive.

<p>Second, what is this business with the "list" keyword?  It is rarely
used, but this is a situation where it is necessary.  When CVSup
creates or consults one of its checkouts files, it uses a filename
which by default is based on the "release" and "tag" values for the
collection.  Specifically, the usual name of a checkouts file is
"checkouts.RELEASE:TAG", where RELEASE and TAG are the "release" and
"tag" settings in your cvsupfile.

<p>In the rather special situation we are addressing here, the
naming conventions for the checkouts files cause a problem.
By default, our first update would produce a file named
"checkouts.cvs:RELENG_2_2_5_RELEASE", while the second update would
look for a file named "checkouts.cvs:RELENG_2_2".  In order for
the second update to benefit from the information garnered in the
first, both updates must use the same checkouts file.  The "list"
specification in the first cvsupfile allows us to accomplish this.  It
overrides the default suffix in the name of the checkouts file, and
forces it to have the same name as will be used in subsequent updates.

<p>Admittedly, this is arcane.  But you only have to do it once.

<p>
<li><a name="adoptupgrade"><em>How can I adopt my FreeBSD-2.2.5
sources, and update them directly to FreeBSD-current?</em></a>

<p>Follow the <a href="#adopt">previous instructions</a>, except change
the <tt>src-all</tt> lines as follows.  In the first update, use:

<pre>
    src-all tag=RELENG_2_2_5_RELEASE list=cvs
</pre>

In subsequent updates, use:

<pre>
    src-all tag=.
</pre>

Note carefully: that's a period following the <tt>tag=</tt> part.
Don't leave it out.

<p>
<h3>Understanding cvsupfiles</h3>

<p>
<li><a name="default"><em>Which things belong on "*default" lines
in the cvsupfile, and which belong on the lines for individual
collections?</em></a>

<p>It doesn't make any difference.  This cvsupfile:

<pre>
    *default host=cvsup3.freebsd.org
    *default base=/usr
    *default prefix=/usr
    *default release=cvs
    *default delete use-rel-suffix
    *default tag=.
    src-all
</pre>

could just as well be expressed as a single line, like this:

<pre>
    src-all host=cvsup3.freebsd.org base=/usr prefix=/usr release=cvs delete use-rel-suffix tag=.
</pre>

<p>Using the "*default" lines can make your cvsupfile easier to read,
by shortening the lines.  They can also make your cvsupfile more
concise if you are receiving several collections.

<p>
<li><a name="delete"><em>What does the cvsupfile's "delete"
keyword do?</em></a>

<p>It gives CVSup permission to remove files on your machine.  For
example, suppose you have a file "foo" which you originally received
using CVSup.  Now the maintainer of the server host deletes "foo".
When you next run CVSup, if "delete" is specified in your cvsupfile
then CVSup will delete "foo" on your machine.  Otherwise it will leave
it alone.

<p>Except for a few unusual applications, you should always specify
"delete" in your cvsupfile.

<p>
<li><a name="delnotdflt"><em>If I should always specify "delete",
then why isn't it the default?</em></a>

<p>Originally CVSup was designed to be a drop-in replacement for sup.
Because of that, the defaults had to be the same whether they made
sense or not.

<p>
<h3>Refuse Files</h3>

<p>
<li><a name="refuse"><em>Help! I can't get "refuse" files to work.</em></a>

<p>
Don't feel bad.  Many people find them confusing.  But they really
do work.

<p>
The most common errors people make with refuse files are:

<p>
<ol>
<li>Specifying the patterns incorrectly.
<li>Putting the refuse file in the wrong directory.
<li>Giving the refuse file the wrong name.
</ol>

<p>
We cover these problems in the following items.

<p>
<li><a name="refuse-patterns"><em>How do I specify the patterns in a
refuse file?</em></a>

<p>
The most important thing to remember is that the patterns in refuse
files are relative to the <em>prefix</em>, which is often not what
you think of as the logical root of a particular collection.  To
determine the prefix, look at your cvsupfile.  Does it contain
something like this?

<pre>
    *default prefix=<em>/some/directory</em>
</pre>

Usually it will.  In that case <em>/some/directory</em> is the prefix.
Otherwise, the prefix is the same as the <em>base</em>.  To determine
the base, see <a href="#refuse-where">this</a>.

<p>
Once you have determined your prefix, put yourself in that
directory.  Then figure out the relative paths of the files and/or
directories you want to block, and make patterns that match them.
Put these patterns into your refuse file separated by whitespace.
You can put each pattern on a separate line, or put several on each
line.  Either way works.

<p>
<li><a name="refuse-example"><em>How about an example of a refuse
file?</em></a>

<p>
OK.  Suppose you use CVSup to receive the FreeBSD documentation
files (the "doc-all" collection), using the <em>doc-supfile</em>
example from <em>/usr/share/examples/cvsup</em>.  Here's what that
cvsupfile looks like, stripped of comments:

<pre>
    *default host=CHANGE_THIS.FreeBSD.org
    *default base=/usr
    *default prefix=/usr
    *default release=cvs tag=.
    *default delete use-rel-suffix
    *default compress
    doc-all
</pre>

As you can see, the prefix is <em>/usr</em>.  Relative to there, the
entire "doc-all" collection is placed into a subdirectory named
<em>doc</em>, which itself contains these files and subdirectories:

<pre>
    FAQ/                    handbook/               ru_SU.KOI8-R/
    Makefile                ja/                     sgml/
    en/                     ja_JP.EUC/              share/
    en_US.ISO_8859-1/       ja_JP.eucJP/            zh/
    es/                     ru/                     zh_TW.Big5/
    es_ES.ISO_8859-1/       ru_RU.KOI8-R/
</pre>

Now let's suppose you're not interested in the Spanish, Japanese,
Russian, or Taiwanese versions of the documentation.  So you want to
refuse the directories whose names begin with "es", "ja", "ru", and
"zh".  The correct patterns <em>relative to the prefix</em> are:

<pre>
    doc/es*
    doc/ja*
    doc/ru*
    doc/zh*
</pre>

<p>
<li><a name="refuse-blockfiles"><em>My refuse file works for
directories, but I can't seem to make it block individual files.</em></a>

<p>
The patterns you specify must match the names of the files on the
<em>server</em>.  If the files are coming from a CVS repository (the
usual case), then on the server they are RCS files.  And RCS files
always have names that end in ",v".  Your patterns must take that
into account.

<p>
For example, suppose you want to block the <em>Makefile</em> in
the example above.  The pattern "<tt>doc/Makefile</tt>" won't work,
because on the server the file's name has a ",v" appended to it.
The correct pattern to use is

<pre>
    doc/Makefile,v
</pre>

or better still

<pre>
    doc/Makefile*
</pre>

which will match the file on the server whether it is an RCS file or
not.

<p>
<li><a name="refuse-where"><em>Where should I put my refuse files?</em></a>

<p>
First you must determine your <em>base</em> directory.

<p>
<ol>
<p><li>When you run the "cvsup" program, do you use the "-b
<em>pathname</em>" option?  (Most users don't.)  If so, that
<em>pathname</em> is your base.  Otherwise ...
<p><li>Does your cvsupfile contain a "base=<em>pathname</em>"
specification?  (Many of them do.)  If so, that <em>pathname</em> is
your base.  Otherwise ...
<p><li>Your base is the built-in default, "/usr/local/etc/cvsup".
</ol>

<p>
Next you must determine your <em>collDir</em>, the subdirectory of
<em>base</em> where CVSup keeps track of your collections.

<p>
<ol>
<p><li>When you run the "cvsup" program, do you use the "-c
<em>directory</em>" option?  (Must users don't.)  If so, that
<em>directory</em> is your <em>collDir</em>.  Otherwise ...
<p><li>Your <em>collDir</em> is the built-in default, "sup".
</ol>

<p>
Finally, you must know the name of the collection you want to
restrict, for example, "doc-all".

<p>
Combine those three items with a slash after each one, and then tack
"refuse" on the end.  That's where to put your refuse file.  For the
<a href="#refuse-example">example</a> we've been using, it works
out to

<pre>
    /usr/sup/doc-all/refuse
</pre>

assuming you don't use the "-b" or "-c" option when you run CVSup.

<p>
<li><a name="refuse-global"><em>Is there a way to create a global
refuse file that will apply to all collections?</em></a>

<p>
Yes.  Simply leave out the name of the collection and the slash
that follows it when you formulate the name of the file.  In the
previous example, the global refuse file would be named

<pre>
    /usr/sup/refuse
</pre>

<p>
<h3>CVSup and Firewalls</h3>

<p>
<li><a name="fwtk"><em>How can I make CVSup work through my TIS FWTK
firewall?</em></a>

<p>
The following instructions were kindly submitted by Alan Strassberg:
<p>
<ol>
<li>Add this line to /etc/services:
<pre>
    cvsup   5999/tcp        # CVSup
</pre>
<p>
<li>Add the following to /etc/inetd.conf:
<pre>
    cvsup stream tcp nowait root /usr/local/etc/plug-gw plug-gw cvsup
</pre>
and send a SIGHUP to inetd.
<p>
<li>Add the following to /usr/local/etc/netperm-table (or whatever
the file is named on your system):
<pre>
    plug-gw: port cvsup <em>A.B.C.D</em> -plug-to <em>W.X.Y.Z</em> -port cvsup
</pre>
where <em>A.B.C.D</em> is the IP address of the internal machine,
and <em>W.X.Y.Z</em> is the IP address of the CVSup server.
<p>
<li>In your cvsupfile, set the CVSup server to be your firewall:
<pre>
    *default  host=gatekeeper.foo.com
</pre>
<p>
<li>When you invoke the cvsup client, include "<tt>-P m</tt>" on the
command line.
</ol>

<p>
Troubleshooting: you should be able to telnet from the internal
machine to the firewall on port 5999 and see the CVS server greeting:
<pre>
    % telnet gatekeeper.foo.com 5999
    OK 15 5 REL_15_4_2 CVSup server ready
</pre>
If the greeting does not appear, run <tt>netstat -na</tt> on the
firewall and verify that it is listening on port 5999:
<pre>
    % netstat -na | grep 5999
    ...
    tcp  0  0  *.5999        *.*                    LISTEN
</pre>

<p>
<h3>Problems Using CVSup</h3>

<p>
<li><a name="cksum"><em>Why has CVSup suddenly started giving me
lots of messages saying, "Checksum mismatch -- will transfer entire
file"?  Every file gets a "fixup" and that is really slowing down my
updates.</em></a>

<p>
Both you and your friendly server administrator need to upgrade to
CVSup 15.4 or later.  That will solve this problem.

<p> CVSup upgrades an RCS file by deconstructing it on the server,
sending only the pieces that have changed to the client, and
reconstructing the file on the client.  (It's roughly patterned after
the transporter on the starship Enterprise.)  CVSup then compares the
MD5 checksum of the reconstructed file with that of the original on
the server, to make sure that the process worked correctly.

<p> Unfortunately, recent releases of CVS have introduced some
gratuitous changes in the format of the RCS files that they write.
These are simply changes in white space, which have no bearing on
the logical meaning of the file.  However, the result is that an RCS
file constructed by the CVSup client no longer matches the original
file byte-by-byte as before.  Even though the reconstructed file
is logically identical to the original, it does not have the same
checksum.  This causes older versions of CVSup to reject the updated
file and use a fixup to re-transfer the entire file.

<p> To solve this problem, CVSup 15.4 introduces a <em>logical</em>
checksum which is used only for RCS files.  Instead of blindly
computing a byte-by-byte checksum over the entire file, the new
checksum algorithm carefully canonicalizes the file so that irrelevant
white space differences are ignored.  The logical checksum should
make CVSup immune to any future problems of this nature.

<p>
<li><a name="fwhang"><em>When I try to run CVSup, it says
it has connected to the server, but then it just hangs.  What's
wrong?</em></a>

<p> You are behind a firewall which is blocking attempts by the CVSup
server to establish a second TCP connection to your client.  Add
the option "<tt>-P m</tt>" to your <tt>cvsup</tt> command line, and
everything should work fine.

<p>
<li><a name="debugkernel"><em>Whenever I run CVSup under FreeBSD, I
get zillions of messages like this: </em><tt>fatal process exception:
page fault, fault VA = 0x11a610</tt>.</a>

<p>
When you built your FreeBSD kernel, you included the undocumented
"<tt>options DEBUG</tt>" in the kernel config file.  Don't do that.

<p>
<li><a name="bsdos"><em>I tried to run the FreeBSD binary of CVSup
under BSD/OS, but it dumped core right away.  Isn't that supposed
to work?</em></a>

<p>
Yes, the statically linked FreeBSD binaries work fine under other
BSD-derived operating systems.  But for some of them, including
BSD/OS, you have to add "<tt>@M3novm</tt>" to the command line.

<p>
CVSup is written in Modula-3, and its runtime system uses a
sophisticated garbage collector which exploits hooks into the VM
subsystem of the operating system to gain better interactive
performance.  This feature stumbles upon an incompatibility between
BSD/OS and FreeBSD, causing the core dumps.  The cryptic argument
"<tt>@M3novm</tt>" disables the VM hooks and makes it possible to
run FreeBSD binaries under other BSD-derived operating systems.

<p>
<li><a name="missingtag"><em>I tried to update my files with CVSup,
but all I got were a bunch of strange looking files whose names
all ended with ",v".  Why?</em></a>

<p>Those strange files are <a href="#RCS">RCS</a> files, and CVSup
sent them to you because your cvsupfile told it to.  When you ask
CVSup to send you updates from a CVS repository, there are two
different things you can ask for.  First, you can ask for the source
files to be extracted from the repository and sent to you.  That is
apparently what you wanted in this case.  Second, you can ask for the
raw RCS files (containing all versions of the sources) to be sent to
you.

<p>These two modes of operation are fundamentally different.  Both work
from RCS files in a CVS repository on the server host.  But they use
the RCS files in different ways.  The first mode, called "checkout
mode," extracts a particular version of the sources from the RCS
files, and sends you that version.  The second mode, called "CVS
mode," sends you the RCS files themselves, in the same form as on the
server.  In the cvsupfile, the "tag" and "date" keywords control which
mode is used.  If either of these keywords is present, then CVSup
uses checkout mode to send you a set of source files.  If neither
"tag" nor "date" is present, then CVSup uses CVS mode to send you
the RCS files.

<p>Assuming you want the most recent version of the sources, you simply
need to add "tag=." to your supfile.

<p>
<h3><a name="checkouts">Checkouts Files</a></h3>

<p>
<li><a name="whatarecheckouts"><em>What are these "checkouts" files I
hear about occasionally?</em></a>

<p>In order to update your files efficiently, CVSup needs to know
what you've already got.  It stores this information in files called
"checkouts" files.  Each time you run cvsup, it reads your checkouts
files to see which files (and which revisions of them) you have.  As
it updates your files, it also updates the information in the
checkouts files.

<p>Confusingly, checkouts files are also sometimes referred to as
"list" files.

<p>
<li><a name="lostcheckouts"><em>This sounds dangerous.  What if I
accidentally delete one of my checkouts files?</em></a>

<p>It is not a big problem.  If CVSup can't find a checkouts file
that it needs, it falls back on other methods of determining which
files you have.  One such method is to compute checksums (MD5 file
signatures) for each of your files, and use those to figure out
which file revisions you have.  This is perfectly safe, but it is
inefficient.  It slows down your update and also puts a heavier load
on the server.

<p>
<li><a name="badcheckouts"><em>What if my checkouts file gets
corrupted somehow?</em></a>

<p>CVSup will detect the problem and quit, with a message suggesting
that you delete the corrupted file and try again.  If you follow the
suggestion, it will complete your update using the fallback methods
mentioned above, and recreate your checkouts file for next time.

<p>
<li><a name="extrafiles"><em>Is there anything at all that can go
wrong if I lose a checkouts file?</em></a>

<p>There is just one thing that can go wrong, and it's not very
serious.  CVSup will only delete files that are listed in its
checkouts file.  Thus if you lose your checkouts file, and then a
file "foo" is deleted on the server host, and then you run CVSup,
your file "foo" will not be deleted.

<p>Files are never supposed to be deleted from a CVS repository, so
this isn't much of a problem in real life.  But to be safe, you
should run CVSup sooner rather than later, if you find that you've
lost a checkouts file.

<p>
<h3>Local Modifications in your CVS Repository</h3>

<p>
<li><a name="canilocal"><em>Can I check my own local changes into
a CVS repository that I update with CVSup from a master site?</em></a>

<p>
If you are careful and if you understand what is going on behind the
scenes, you can make this work.  CVSup was designed to allow extra
locally checked-in revisions to coexist in the RCS files along with
the revisions taken from the master repository on the server.  Because
CVSup understands the structure of RCS files, it is able to bring in
new revisions from the server without disturbing your own revisions
that you have checked in locally.  Unfortunately, certain logistical
issues make this capability awkward to use in practical situations.

<p>
To keep local revisions in your copy of the CVS repository, you have
to:

<ul>
<p><li>Instruct CVSup not to delete them.
<p><li>Ensure that revision numbers of your local revisions don't
conflict with the numbers of current or future revisions in the
master copy of each RCS file at the server.
</ul>

<p>
We cover these topics separately below.

<p>
<li><a name="nodelete"><em>How can I keep CVSup from deleting the
revisions I have checked in locally?</em></a>

<p>
Simply remove the "delete" keyword from your cvsupfile.  When present,
this keyword gives CVSup permission to delete extra revisions from the
RCS files.  It also permits CVSup to delete entire RCS files, provided
that it created them in the first place.  By removing the "delete"
keyword, you can prevent CVSup from removing extra revisions as well
as entire RCS files.  However, it is very important to understand the
consequences of removing the "delete" keyword.

<p>
First, suppose that one or more RCS files are intentionally removed
from the CVS repository at the master site.  Without the "delete"
keyword, CVSup will not propagate these file removals to your site.
Thus you will have some RCS files in your repository that otherwise
shouldn't be there.

<p>
In an ideal world, this would not be a problem.  That is because, in
an ideal world, one <em>never</em> deletes an RCS file from a CVS
repository.  Thus, the situation should never arise.

<p>
Unfortunately, most administrators don't manage their repositories
quite so idealistically.  Committers make mistakes and check files
into the wrong locations.  Most administrators will manually repair
such errors by moving the files in the repository, rather than
live with the mistake forever.  As another example, in any large
repository, some files eventually become completely obsolete.
Eventually, developers will complain about the wasted disk space and
the clutter in the repository, and the repository administrator will
respond by deleting the files.

<p>
Usually, undeleted RCS files don't cause any problems, and they can
be safely ignored.  This is especially true if the repository
administrator at the master site has taken care to mark the files
"dead" on all branches with "cvs remove" a few weeks before completely
removing the unwanted RCS files.  Nevertheless, extra RCS files can
cause problems in some cases, and you need to be aware of that.

<p>
<li><a name="revconflicts"><em>How can I keep the revision numbers of
my local check-ins from conflicting with revision numbers originating
at the master site?</em></a>

<p>
It is difficult, because CVS chooses the revision numbers itself.
One way around this is to modify CVS slightly.  Before discussing
that, though, the first rule of thumb is to create a new branch to
hold your local changes.  Don't try to check your local changes into
the main branch or a branch that exists in the master repository.
Doing so would make revision number collisions very likely, sooner
or later.

<p>
If your local revisions are on their own branch, then the problem is
reduced to ensuring that your branch has a unique revision number
which will never be duplicated in the master repository.  The
easiest way to accomplish this is to modify CVS.  The version of CVS
released with FreeBSD includes such a modification.  In that
version, you can influence the revision numbers of branches by
setting the environment variable <tt>CVS_LOCAL_BRANCH_NUM</tt>.
This variable should be set to an integer value, and CVS will use
that as the starting point when choosing revision numbers for new
branches.  By default, CVS allocates branch numbers starting with 1.
So a high value such as 1000 makes a good choice.  New branches at
the master site will receive low revision numbers, while your own
local branches will receive high revision numbers.  Thus the two
won't conflict.

<p>
When using this method, it is of the utmost importance that
committers do <strong>not</strong> set <tt>CVS_LOCAL_BRANCH_NUM</tt>
when creating branches in the master repository.

<p>
If you don't have a version of CVS that supports
<tt>CVS_LOCAL_BRANCH_NUM</tt>, it is still possible to avoid
conflicts with little cooperation from the master site.  Simply
create a branch in the master repository, declare it to be reserved
for local modifications, and leave it unused in the master
repository.

<p>
<h3>Setting Up a CVSup Server</h3>

<p>
<li><a name="testserver"><em>How can I set up a simple collection to
test the CVSup server?</em></a>

<p>
Make an empty directory somewhere.  We'll call that directory
<em>base</em>.  Cd into <em>base</em> and do a <tt>mkdir -p
sup/test</tt>.

<p>
Next, cd into <tt>sup/test</tt> and create a file named <tt>releases</tt>
with one line in it like this:

<pre>
    cvs list=list.cvs prefix=<em>prefix</em>
</pre>

In the above, replace <em>prefix</em> with the absolute path to some
CVS repository on your machine, e.g., <tt>/usr/cvs</tt>.  If you don't
have a CVS repository, you can use any directory that has some files
in it.  But RCS files are the best for testing purposes.

<p>
In the same directory as the <tt>releases</tt> file, make a file named
<tt>list.cvs</tt>.  It should contain a single line:

<pre>
    upgrade src/bin
</pre>

Here, replace <tt>src/bin</tt> with the path to some reasonably-sized
subtree of your CVS repository, relative to <em>prefix</em>.
For example, if <em>prefix</em> is <tt>/usr/cvs</tt> in your
<tt>releases</tt> file, and the line in <tt>list.cvs</tt> is as above,
then the transferred subtree will be <tt>/usr/cvs/src/bin</tt>.

<p>
You have just created a CVSup collection named "test" with a release
named "cvs".  You can run the server like this:

<pre>
    cvsupd -b <em>base</em>
</pre>

replacing <em>base</em> appropriately with the pathname of the
base directory that you created above.  If you run it this way,
<tt>cvsupd</tt> will print its log messages to stdout.  It will serve
exactly one client and then exit.  To run multiple tests, you have to
restart the server each time.  Alternatively, you can run the server
like this:

<pre>
    cvsupd -b <em>base</em> -C 1 -l /dev/stdout
</pre>

and it will become a daemon and serve clients indefinitely until you
kill it manually.  Note, it doesn't matter what your working directory
is when you start the server.

<p>
Now, create a separate empty directory where you'll run the client
to receive the updates from the server.  We'll call that directory
<em>dest</em>.  In <em>dest</em>, make a file <tt>supfile</tt> that
looks like this:

<pre>
    *default host=localhost
    *default base=.
    *default release=cvs
    *default delete use-rel-suffix
    test
</pre>

(Notice that there is a "." in "<tt>base=.</tt>".)

Make sure the server is running, and then, still in <em>dest</em>, run
<tt>cvsup</tt> in the usual way.  The simplest command is this:

<pre>
    cvsup supfile
</pre>

but you can add <tt>-g -L 2</tt> to disable the GUI if you wish.

<p>
If your CVSup client was built with the GUI, press the start button.
The non-GUI client starts automatically.  At this point, your disk
light will turn into a 50-watt beacon and your hard drive will make
that noise that says, "I'm really really <em>really</em> busy."  When
it's done, you should find the updated files under your <em>dest</em>
directory.  There will also be a directory <tt>sup</tt> which is used
by <tt>cvsup</tt> to record its state.

<p>
Assuming that worked, you can get arbitrarily thorough in testing
the rest of it.  By manipulating the source RCS files, you can add
deltas and/or tags, and then make sure they propagate when you do
another update.  You can also try deleting RCS files entirely, and
adding new ones.  On the client side, you can add <tt>tag=</tt>
and/or <tt>date=</tt> specifications to the supfile.  Generally,
if the software works at all on a given platform, it's likely to
work completely.  Almost all of the functionality is contained in
OS-independent code.

<p>
One caveat:  Doing an update all on one machine via localhost really
hammers a system, particularly the disk subsystem and the network
stack.  It can expose OS bugs that nobody knew existed before.  If
you run into networking-related problems, it might help to use <tt>-P
m</tt> on the <tt>cvsup</tt> command line when you do your updates.

<p>
<li><a name="serversample"><em>Where can I find a set of CVSup
server configuration files to use as an example?</em></a>

<p>
The server configuration files used by the FreeBSD project are
available via CVSup from any FreeBSD mirror site.  To fetch a copy, get
into an empty directory and make a file named <tt>supfile</tt>
containing this text:

<pre>
    *default host=<em>a.mirror.site</em> compress
    *default release=cvs tag=.
    *default base=.
    *default delete use-rel-suffix norsync
    distrib
</pre>

Replace <em>a.mirror.site</em> with any <a
href="http://www.freebsd.org/handbook/mirrors.html">CVSup site
listed in the FreeBSD Handbook</a>.  Run the CVSup client using this
<tt>supfile</tt>.  When it finishes, you'll find the configuration
files in the subdirectory <tt>distrib/cvsup</tt>.  If you wanted to
use these configuration files directly, you'd use that subdirectory as
your <em>base</em> directory, like this:

<pre>
    cvsupd -b distrib/cvsup <em>...</em>
</pre>

In a real setup, you'd specify the base directory as an absolute
pathname, of course.

<p>
<h3><a name="compiling">Building CVSup from the Sources</a></h3>

<p>
<li><a name="notc"><em>I've heard lots of horror stories about
building CVSup from the sources.  Why is that?</em></a>

<p>
The basic problem is that CVSup is written in the programming language
NotC.  What is NotC?  Well, to most people, it really doesn't
matter.  The important thing is that NotC is <strong>not C</strong>.
Consequently, it takes a little extra work to use it.

<p>
In the case of CVSup, NotC means Modula-3.  Modula-3 is an
efficient compiled programming language with excellent built-in
support for important features such as garbage collection
and threads.  For more information about Modula-3, see the
<a href="http://www.research.digital.com/SRC/modula-3/html/home.html">
Modula-3 Home Page</a>.

<p>
Fortunately, Modula-3 ports exist for
<a href="http://www.research.digital.com/SRC/modula-3/html/platforms.html">
many platforms</a>.  If there is already a port for your platform of
choice, then you've already cleared the biggest hurdle to building
CVSup.

<p>
A second problem that many people run into is that building the
Modula-3 compiler and runtime system requires a lot of virtual
memory.  You will need on the order of 64 MB of available virtual
memory to build it.  (Building CVSup itself requires less than
that.)  You will also need to ensure that your resource limits are
set high enough.  These are controlled by the "ulimit" command in
<tt>sh</tt>-like shells, or by the "limit" command in <tt>csh</tt>.

<p>
Third, by default you have to have X11 on your system to build the
Modula-3 runtime.  It is possible to build Modula-3 without X11, but
to do so you have to edit the file <tt>m3/src/m3makefile</tt> and
comment out the packages that depend on X11.

<p>
<li><a name="fromsource"><em>What steps are involved in building
CVSup from the sources?</em></a>

<p>
<ol type="A">

<p><li>Build and install the Modula-3 compiler and runtime.  This is
the hardest part of the process.

<p><li>Build and install the "zlib" compression library.  This is
quite painless.  See the
<a href="ftp://ftp.cdrom.com/pub/infozip/zlib/">zlib FTP site</a>
for details.

<p><li>Build and install CVSup.  This also is relatively painless.
</ol>

<p>
<li><a name="mswin"><em>Has CVSup been ported to Windows 95 or NT?</em></a>

<p>
No, CVSup does not currently work on Windows platforms.  It relies
on a number of features which are specific to POSIX-like operating
systems.

<p>
<h3>Compatibility</h3>

<p>
<li><a name="verscompat"><em>When a new version of CVSup comes
out, do the clients and the server have to be upgraded at the same
time?</em></a>

<p>
No.  All releases of CVSup that have ever been made public will
interoperate with each other.  You can use an old client with a new
server, or a new client with an old server.  Of course, the feature
set is limited to what is supported by the older component.  So it is
always a good idea to upgrade both the client and the server when a
new version is released.

<p>
<li><a name="supcompat"><em>Can I use the CVSup client to get updates from a SUP
server?</em></a>

<p>No.  Although the CVSup client can use supfiles written for SUP,
the two packages are otherwise incompatible.

</ol>

<hr>
<address>
$Id: faq.html,v 1.12 1999/08/28 17:29:00 jdp Exp $<br>
Copyright &copy; 1998, 1999 John D. Polstra<br>
</address>
</body>
</html>