path: root/en/handbook/cutting-edge/chapter.sgml

<!--
     The FreeBSD Documentation Project

     $Id: chapter.sgml,v 1.22 1999-07-28 20:23:20 nik Exp $
-->

<chapter id="cutting-edge">
  <title>The Cutting Edge: FreeBSD-current and FreeBSD-stable</title>
  
  <para>FreeBSD is under constant development between releases.  For people
    who want to be on the cutting edge, there are several easy mechanisms for
    keeping your system in sync with the latest developments.  Be warned: the
    cutting edge is not for everyone! This chapter will help you decide if you
    want to track the development system, or stick with one of the released
    versions.</para>
  
  <sect1 id="current">
    <title>Staying Current with FreeBSD</title>
    
    <para><emphasis>Contributed by &a.jkh;.</emphasis></para>
    
    <sect2>
      <title>What is FreeBSD-current?</title>
      
      <para>FreeBSD-current is, quite literally, nothing more than a daily
	snapshot of the working sources for FreeBSD.  These include work in
	progress, experimental changes and transitional mechanisms that may or
	may not be present in the next official release of the software.
	While many of us compile almost daily from FreeBSD-current sources,
	there are periods of time when the sources are literally
	un-compilable.  These problems are generally resolved as expeditiously
	as possible, but whether or not FreeBSD-current sources bring disaster
	or greatly desired functionality can literally be a matter of which
	part of any given 24 hour period you grabbed them in!</para>
    </sect2>
    
    <sect2>
      <title>Who needs FreeBSD-current?</title>
      
      <para>FreeBSD-current is made generally available for 3 primary interest
	groups:</para>
	  
      <orderedlist>
	<listitem>
	  <para>Members of the FreeBSD group who are actively working on some
	    part of the source tree and for whom keeping &ldquo;current&rdquo;
	    is an absolute requirement.</para>
	</listitem>
	
	<listitem>
	  <para>Members of the FreeBSD group who are active testers, willing
	    to spend time working through problems in order to ensure that
	    FreeBSD-current remains as sane as possible. These are also people
	    who wish to make topical suggestions on changes and the general
	    direction of FreeBSD.</para>
	</listitem>
	
	<listitem>
	  <para>Peripheral members of the FreeBSD (or some other) group who
	    merely wish to keep an eye on things and use the current sources
	    for reference purposes (e.g. for <emphasis>reading</emphasis>, not
	    running).  These people also make the occasional comment or
	    contribute code.</para>
	</listitem>
      </orderedlist>
    </sect2>
    
    <sect2>
      <title>What is FreeBSD-current <emphasis>not</emphasis>?</title>
      
      <orderedlist>
	<listitem>
	  <para>A fast-track to getting pre-release bits because you heard
	    there is some cool new feature in there and you want to be the
	    first on your block to have it.</para>
	</listitem>
	
	<listitem>
	  <para>A quick way of getting bug fixes.</para>
	</listitem>
	
	<listitem>
	  <para>In any way &ldquo;officially supported&rdquo; by us.  We do
	    our best to help people genuinely in one of the 3
	    &ldquo;legitimate&rdquo; FreeBSD-current categories, but we simply
	    <emphasis>do not have the time</emphasis> to provide tech support
	    for it. This is not because we are mean and nasty people who do
	    not like helping people out (we would not even be doing FreeBSD if
	    we were), it is literally because we cannot answer 400 messages a
	    day <emphasis>and</emphasis> actually work on FreeBSD! I am sure
	    that, if given the choice between having us answer lots of
	    questions or continuing to improve FreeBSD, most of you would vote
	    for us improving it.</para>
	</listitem>
      </orderedlist>
    </sect2>
    
    <sect2>
      <title>Using FreeBSD-current</title>
      
      <orderedlist>
	<listitem>
	  <para>Join the &a.current; and the &a.cvsall; .  This is not just a
	    good idea, it is <emphasis>essential</emphasis>.  If you are not
	    on the <emphasis>FreeBSD-current</emphasis> mailing list, you will
	    not see the comments that people are making about the current
	    state of the system and thus will probably end up stumbling over a
	    lot of problems that others have already found and solved.  Even
	    more importantly, you will miss out on important bulletins which
	    may be critical to your system's continued health.</para>

	  <para>The <email>cvs-all</email> mailing list will allow you to see
	    the commit log entry for each change as it is made along with any
	    pertinent information on possible side-effects.</para>

	  <para>To join these lists, send mail to
	      &a.majordomo; and specify:

	    <programlisting>
subscribe freebsd-current
subscribe cvs-all</programlisting>

	    in the body of your message.  Optionally, you can also say
	    <literal>help</literal> and Majordomo will send you full help on
	    how to subscribe and unsubscribe to the various other mailing
	    lists we support.</para>
	</listitem>
	
	<listitem>
	  <para>Grab the sources from <hostid
	      role="fqdn">ftp.FreeBSD.org</hostid>.  You can do this in three
	    ways:</para>
	  
	  <orderedlist>
	    <listitem>
	      <para>Use the <application><link
		    linkend="ctm">CTM</link></application> facility.  Unless
		you  have a good TCP/IP connection at a flat rate, this is
		the way to do it.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Use the <link linkend="cvsup">cvsup</link> program with
		<ulink
		  URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/standard-supfile">this
		  supfile</ulink>.  This is the second most recommended
		method, since it allows  you to grab the entire collection
		once and then only what has changed from then on.  Many people
		run cvsup from cron and keep their sources up-to-date
		automatically.  For a fairly easy interface to this, simply
		type:</para>
    
	      <blockquote><screen>&prompt.root; <userinput>pkg_add -f \
ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></screen></blockquote>
	    </listitem>
	    
	    <listitem>
	      <para>Use <command>ftp</command>.  The source tree for
		FreeBSD-current is always &ldquo;exported&rdquo; on: <ulink
		  URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current</ulink>.
		We also use <command>wu-ftpd</command> which allows
		compressed/tar'd grabbing of whole trees.  e.g. you
		see:</para>
	      
	      <screen>usr.bin/lex</screen>
	      
	      <para>You can do:
					
		<screen><prompt>ftp&gt;</prompt> <userinput>cd usr.bin</userinput>
<prompt>ftp&gt;</prompt> <userinput>get lex.tar.Z</userinput></screen>
		
		and it will get the whole directory for you as a compressed
		tar file.</para>
	    </listitem>
	  </orderedlist>
	</listitem>
	
	<listitem>
	  <para>Essentially, if you need rapid on-demand access to the source
	    and communications bandwidth is not a consideration, use
	    <command>cvsup</command> or <command>ftp</command>.  Otherwise,
	    use <application>CTM</application>.</para>

	  <para>If you are grabbing the sources to run, and not just look at,
	    then grab <emphasis>all</emphasis> of current, not just selected
	    portions.  The reason for this is that various parts of the source
	    depend on updates elsewhere, and trying to compile just a subset
	    is almost guaranteed to get you into trouble.</para>

	  <para>Before compiling current, read the Makefile in
	    <filename>/usr/src</filename> carefully.  You should at least run
	    a <link linkend="makeworld">make world</link> the first time
	    through as part of the upgrading process.  Reading the &a.current;
	    will keep you up-to-date on other bootstrapping procedures that
	    sometimes become necessary as we move towards the next
	    release.</para>
	</listitem>
	      
	<listitem>
	  <para>Be active! If you are running FreeBSD-current, we want to
	    know what you have to say about it, especially if you have
	    suggestions for enhancements or bug fixes. Suggestions with
	    accompanying code are received most enthusiastically!</para>
	</listitem>
      </orderedlist>
    </sect2>
  </sect1>
  
  <sect1 id="stable">
    <title>Staying Stable with FreeBSD</title>
    
    <para><emphasis>Contributed by &a.jkh;.</emphasis></para>
    
    <sect2>
      <title>What is FreeBSD-stable?</title>
      
      <para>FreeBSD-stable is our development branch for a more low-key and
	conservative set of changes intended for our next mainstream release.
	Changes of an experimental or untested nature do not go into this
	branch (see <link linkend="current">FreeBSD-current</link>).</para>
    </sect2>
    
    <sect2>
      <title>Who needs FreeBSD-stable?</title>
      
      <para>If you are a commercial user or someone who puts maximum stability
	of their FreeBSD system before all other concerns, you should consider
	tracking <emphasis>stable</emphasis>.  This is especially true if you
	have installed the most recent release (<ulink
	  URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/&rel.current;-RELEASE">&rel.current;-RELEASE</ulink>
	at the time of this writing) since the <emphasis>stable</emphasis>
	branch is effectively a bug-fix stream relative to the previous
	release.</para>
      
      <warning>
	<para>The <emphasis>stable</emphasis> tree endeavors, above all, to be
	  fully compilable and stable at all times, but we do occasionally
	  make mistakes (these are still active sources with
	  quickly-transmitted updates, after all).  We also do our best to
	  thoroughly test fixes in <emphasis>current</emphasis> before
	  bringing them into <emphasis>stable</emphasis>, but sometimes our
	  tests fail to catch every case.  If something breaks for you in
	  <emphasis>stable</emphasis>, please let us know
	  <emphasis>immediately!</emphasis> (see next section).</para>
      </warning>
    </sect2>
    
    <sect2>
      <title>Using FreeBSD-stable</title>
      
      <orderedlist>
	
	<listitem>
	  <para>Join the &a.stable;.  This will keep you informed of
	    build-dependencies that may appear in <emphasis>stable</emphasis>
	    or any other issues requiring special attention.  Developers will
	    also make announcements in this mailing list when they are
	    contemplating some controversial fix or update, giving the users a
	    chance to respond if they have any issues to raise concerning the
	    proposed change.</para>
	  
	  <para>The <email>cvs-all</email> mailing list will allow you to see
	    the commit log entry for each change as it is made along with any
	    pertinent information on possible side-effects.</para>

	  <para>To join these lists, send mail to &a.majordomo; and specify:

	    <programlisting>
subscribe freebsd-stable
subscribe cvs-all</programlisting>

	    in the body of your message.  Optionally, you can also say
	    <literal>help</literal> and Majordomo will send you full help on
	    how to subscribe and unsubscribe to the various other mailing
	    lists we support.</para>
	</listitem>
	
	<listitem>
	  <para>If you are installing a new system and want it to be as stable
	    as possible, you can simply grab the latest dated branch snapshot
	    from <ulink
	      url="ftp://releng3.FreeBSD.org/pub/FreeBSD/">ftp://releng3.FreeBSD.org/pub/FreeBSD/</ulink>
	    and install it like any other release.</para>

	  <para>If you are already running a previous release of 2.2 and wish
	    to upgrade via sources then you can easily do so from <hostid
	      role="fqdn">ftp.FreeBSD.org</hostid>.  This can be done in one
	    of three ways:</para>
		  
	  <orderedlist>
	    <listitem>
	      <para>Use the <application><link
		    linkend="ctm">CTM</link></application> facility.  Unless
		you have a good TCP/IP connection at a flat rate, this is
		the way to do it.</para>
	    </listitem>
	    
	    <listitem>
	      <para>Use the <link linkend="cvsup">cvsup</link> program with
		<ulink
		  URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/stable-supfile">this
		  supfile</ulink>.  This is the second most recommended
		method, since it allows  you to grab the entire collection
		once and then only what has changed from then on.  Many people
		run cvsup from cron to keep their sources up-to-date
		automatically.  For a fairly easy interface to this, simply
		type;</para>
	      
<blockquote><screen>&prompt.root; <userinput>pkg_add -f \
ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupit.tgz</userinput></screen></blockquote>
	    </listitem>
		    
	    <listitem>
	      <para>Use <command>ftp</command>.  The source tree for
		FreeBSD-stable is always &ldquo;exported&rdquo; on: <ulink
		  URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable</ulink></para>
		      
	      <para>We also use <command>wu-ftpd</command> which allows
		compressed/tar'd grabbing of whole trees.  e.g. you
		see:</para>

	      <screen>usr.bin/lex</screen>
	      
	      <para>You can do:
		
		<screen><prompt>ftp&gt;</prompt> <userinput>cd usr.bin</userinput>
<prompt>ftp&gt;</prompt> <userinput>get lex.tar.Z</userinput></screen>
			
		and it will get the whole directory for you as a compressed
		tar file.</para>
	    </listitem>
	  </orderedlist>
	</listitem>
	
	<listitem>
	  <para>Essentially, if you need rapid on-demand access to the source
	    and communications bandwidth is not a consideration, use
	    <command>cvsup</command> or <command>ftp</command>.  Otherwise,
	    use <application>CTM</application>.</para>
	</listitem>
	
	<listitem>
	  <para>Before compiling stable, read the Makefile in
	    <filename>/usr/src</filename> carefully.  You should at least run
	    a <link linkend="makeworld">make world</link> the first time
	    through as part of the upgrading process.  Reading the &a.stable;
	    will keep you up-to-date on other bootstrapping procedures that
	    sometimes become necessary as we move towards the next
	    release.</para>
	</listitem>
      </orderedlist>
    </sect2>
  </sect1>
  
  <sect1 id="synching">
    <title>Synchronizing Source Trees over the Internet</title>
    
    <para><emphasis>Contributed by &a.jkh;.</emphasis></para>
	
    <para>There are various ways of using an Internet (or email) connection to
      stay up-to-date with any given area of the FreeBSD project sources, or
      all areas, depending on what interests you.  The primary services we
      offer are <link linkend="anoncvs">Anonymous CVS</link>, <link
	linkend="cvsup">CVSup</link>, and <link
	linkend="ctm">CTM</link>.</para>
	
    <para><application>Anonymous CVS</application> and
      <application>CVSup</application> use the <emphasis>pull</emphasis> model
      of updating sources.  In the case of <application>CVSup</application>
      the user (or a cron script) invokes the <command>cvsup</command>
      program, and it interacts with a <command>cvsupd</command> server
      somewhere to bring your files up to date.  The updates you receive are
      up-to-the-minute and you get them when, and only when, you want them.
      You can easily restrict your updates to the specific files or
      directories that are of interest to you.  Updates are generated on the
      fly by the server, according to what you have and what you want to have.
      <application>Anonymous CVS</application> is quite a bit more simplistic
      than CVSup in that it's just an extension to
      <application>CVS</application> which allows it to pull changes directly
      from a remote CVS repository.  <application>CVSup</application> can do
      this far more efficiently, but <application>Anonymous CVS</application>
      is easier to use.</para>
	
    <para><application>CTM</application>, on the other hand, does not
      interactively compare the sources you have with those on the master
      archive or otherwise pull them across..  Instead, a script which
      identifies changes in files since its previous run is executed several
      times a day on the master CTM machine, any detected changes being
      compressed, stamped with a sequence-number and encoded for transmission
      over email (in printable ASCII only).  Once received, these &ldquo;CTM
      deltas&rdquo; can then be handed to the &man.ctm.rmail.1; utility which
      will automatically decode,
      verify and apply the changes to the user's copy of the sources.  This
      process is far more efficient than <application>CVSup</application>, and
      places less strain on our server resources since it is a
      <emphasis>push</emphasis> rather than a <emphasis>pull</emphasis>
      model.</para>

    <para>There are other trade-offs, of course.  If you inadvertently wipe
      out portions of your archive, <application>CVSup</application> will
      detect and rebuild the damaged portions for you.
      <application>CTM</application> won't do this, and if you wipe some
      portion of your source tree out (and don't have it backed up) then you
      will have to start from scratch (from the most recent CVS &ldquo;base
      delta&rdquo;) and rebuild it all with CTM or, with anoncvs, simply
      delete the bad bits and resync.</para>
	
    <para>For more information on <application>Anonymous CVS</application>,
      <application>CTM</application>, and <application>CVSup</application>,
      please see one of the following sections:</para>

    <sect2 id="anoncvs">
      <title>Anonymous CVS</title>
      
      <para><emphasis>Contributed by &a.jkh;</emphasis></para>
      
      <sect3>
	<title><anchor id="anoncvs-intro">Introduction</title>
	
	<para>Anonymous CVS (or, as it is otherwise known,
	  <emphasis>anoncvs</emphasis>) is a feature provided by the CVS
	  utilities bundled with FreeBSD for synchronizing with a remote CVS
	  repository.  Among other things, it allows users of FreeBSD to
	  perform, with no special privileges, read-only CVS operations
	  against one of the FreeBSD project's official anoncvs servers.  To
	  use it, one simply sets the <envar>CVSROOT</envar> environment
	  variable to point at the appropriate anoncvs server and then uses
	  the &man.cvs.1; command to access it like any local
	  repository.</para>

	<para>While it can also be said that the <link
	    linkend="cvsup">CVSup</link> and <emphasis>anoncvs</emphasis>
	  services both perform essentially the same function, there are
	  various trade-offs which can influence the user's choice of
	  synchronization methods.  In a nutshell,
	  <application>CVSup</application> is much more efficient in its usage
	  of network resources and is by far the most technically
	  sophisticated of the two, but at a price.  To use
	  <application>CVSup</application>, a special client must first be
	  installed and configured before any bits can be grabbed, and then
	  only in the fairly large chunks which
	  <application>CVSup</application> calls
	  <emphasis>collections</emphasis>.</para>

	<para><application>Anoncvs</application>, by contrast, can be used to
	  examine anything from an individual file to a specific program (like
	  <command>ls</command> or <command>grep</command>) by referencing the
	  CVS module name.  Of course, <application>anoncvs</application> is
	  also only good for read-only operations on the CVS repository, so if
	  it's your intention to support local development in one repository
	  shared with the FreeBSD project bits then
	  <application>CVSup</application> is really your only option.</para>
      </sect3>
      
      <sect3>
	<title><anchor id="anoncvs-usage">Using Anonymous CVS</title>
	
	<para>Configuring &man.cvs.1; to use an Anonymous CVS repository is a
	  simple matter of setting the <envar>CVSROOT</envar> environment
	  variable to point to one of the FreeBSD project's
	  <emphasis>anoncvs</emphasis> servers.  At the time of this writing,
	  the following servers are available:</para>

	<itemizedlist>
	  <listitem>
	    <para><emphasis>USA</emphasis>:
	      anoncvs@anoncvs.FreeBSD.org:/cvs</para>
	  </listitem>
	</itemizedlist>
	
	<para>Since CVS allows one to &ldquo;check out&rdquo; virtually any
	  version of the FreeBSD sources that ever existed (or, in some cases,
	  will exist <!-- smiley -->:), you need to be familiar with the
	  revision (<option>-r</option>) flag to &man.cvs.1; and what some of
	  the permissible values for it in the FreeBSD Project repository
	  are.</para>

	<para>There are two kinds of tags, revision tags and branch tags.  A
	  revision tag refers to a specific revision.  Its meaning stays the
	  same from day to day.  A branch tag, on the other hand, refers to
	  the latest revision on a given line of development, at any given
	  time.  Because a branch tag does not refer to a specific revision,
	  it may mean something different tomorrow than it means today.</para>
	
	<para>Here are the branch tags that users might be interested
	  in:</para>

	<variablelist>
	  <varlistentry>
	    <term>HEAD</term>
	    
	    <listitem>
	      <para>Symbolic name for the main line, or FreeBSD-current. Also
		the default when no revision is specified.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_3</term>
	    
	    <listitem>
	      <para>The line of development for FreeBSD-3.x, also known as
		FreeBSD-stable.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_2</term>
	    
	    <listitem>
	      <para>The line of development for FreeBSD-2.2.x, also known as
		2.2-stable.  This branch is mostly obsolete. Not valid for
	 	the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_1_0</term>
	    
	    <listitem>
	      <para>The line of development for FreeBSD-2.1.x - this branch is
		largely obsolete.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	
	<para>Here are the revision tags that users might be interested
	  in:</para>
	
	<variablelist>
	  <varlistentry>

            <term>RELENG_3_2_0_RELEASE</term>
                  
            <listitem>
              <para>FreeBSD-3.2.  Not valid for the ports collection.</para>
            </listitem>
          </varlistentry>
        
          <varlistentry>

	    <term>RELENG_3_1_0_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-3.1.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_3_0_0_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-3.0.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_8_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.2.8.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_7_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.2.7.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_6_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.2.6.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_2_5_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.2.5.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_2_2_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.2.2.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_2_1_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.2.1.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_2_0_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.2.0.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_1_7_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.1.7.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_1_6_1_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.1.6.1.  Not valid for the ports
		collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_1_6_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.1.6.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_1_5_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.1.5.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_2_1_0_RELEASE</term>
	    
	    <listitem>
	      <para>FreeBSD-2.1.0.  Not valid for the ports collection.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
	
	<para>When you specify a branch tag, you normally receive the latest
	  versions of the files on that line of development.  If you wish to
	  receive some past version, you can do so by specifying a date with
	  the <option>-D date</option> flag.  See the &man.cvs.1; man page
	  for more details.</para>
      </sect3>
      
      <sect3>
	<title>Examples</title>
	
	<para>While it really is recommended that you read the manual page for
	    &man.cvs.1; thoroughly before doing anything, here are some
	  quick examples which essentially show how to use Anonymous
	  CVS:</para>

	<example>
	  <title>Checking out something from -current (&man.ls.1;) and
	    deleting it again:</title>

	  <screen>
&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs</userinput>
&prompt.user; <userinput>cvs co ls</userinput>
&prompt.user; <userinput>cvs release -d ls</userinput></screen>
	</example>
	
	<example>
	  <title>Checking out the version of ls(1) in the 2.2-stable
	    branch:</title>
	    
	  <screen>
&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs</userinput>
&prompt.user; <userinput>cvs co -rRELENG_2_2 ls</userinput>
&prompt.user; <userinput>cvs release -d ls</userinput></screen>
	</example>
	
	<example>
	  <title>Creating a list of changes (as unidiffs) to &man.ls.1;</title>

	  <screen>
&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs</userinput>
&prompt.user; <userinput>cvs rdiff -u -rRELENG_2_2_2_RELEASE -rRELENG_2_2_6_RELEASE ls</userinput></screen>
	</example>

	<example>
	  <title>Finding out what other module names can be used:</title>
	  
	  <screen>
&prompt.user; <userinput>setenv CVSROOT anoncvs@anoncvs.FreeBSD.org:/cvs</userinput>
&prompt.user; <userinput>cvs co modules</userinput>
&prompt.user; <userinput>more modules/modules</userinput>
&prompt.user; <userinput>cvs release -d modules</userinput></screen>
	</example>
      </sect3>
      
      <sect3>
	<title>Other Resources</title>
	
	<para>The following additional resources may be helpful in learning
	  CVS:</para>
	
	<itemizedlist>
	  <listitem>
	    <para><ulink
		url="http://www.csc.calpoly.edu/~dbutler/tutorials/winter96/cvs/">CVS Tutorial</ulink> from Cal Poly.</para>
	  </listitem>
	  
	  <listitem>
	    <para><ulink url="http://www.cyclic.com">Cyclic Software</ulink>,
	      commercial maintainers of CVS.</para>
	  </listitem>
	  
	  <listitem>
	    <para><ulink
		url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVSWeb</ulink> is
	      the FreeBSD Project web interface for CVS.</para>
	  </listitem>
	</itemizedlist>
      </sect3>
    </sect2>
    
    <sect2 id="ctm">
      <title><application>CTM</application></title>
      
      <para><emphasis>Contributed by &a.phk;.  Updated
	  19-October-1997.</emphasis></para>
      
      <para><application>CTM</application> is a method for keeping a remote
	directory tree in sync with a central one.  It has been developed for
	usage with FreeBSD's source trees, though other people may find it
	useful for other purposes as time goes by.  Little, if any,
	documentation currently exists at this time on the process of creating
	deltas, so talk to &a.phk; for more information should you wish to use
	<application>CTM</application> for other things.</para>
	  
      <sect3>
	<title>Why should I use <application>CTM</application>?</title>
	
	<para><application>CTM</application> will give you a local copy of the
	  FreeBSD source trees.  There are a number of &ldquo;flavors&rdquo;
	  of the tree available.  Whether you wish to track the entire cvs
	  tree or just one of the branches, <application>CTM</application> can
	  provide you the information.  If you are an active developer on
	  FreeBSD, but have lousy or non-existent TCP/IP connectivity, or
	  simply wish to have the changes automatically sent to you,
	  <application>CTM</application> was made for you.  You will need to
	  obtain up to three deltas per day for the most  active branches.
	  However, you should consider having them sent by automatic email.
	  The sizes of the updates are always kept as small as possible.  This
	  is typically less than 5K, with an occasional (one in ten) being
	  10-50K and every now and then a biggie of 100K+ or more coming
	  around.</para>
	    
	<para>You will also need to make yourself aware of the various caveats
	  related to working directly from the development sources rather than
	  a pre-packaged release.  This is particularly true if you choose the
	  &ldquo;current&rdquo; sources.  It is recommended that you read
	  <link linkend="current">Staying current with FreeBSD</link>.</para>
      </sect3>
      
      <sect3>
	<title>What do I need to use <application>CTM</application>?</title>
	
	<para>You will need two things: The <application>CTM</application>
	  program and the initial deltas to feed it (to get up to
	  &ldquo;current&rdquo; levels).</para>
	    
	<para>The <application>CTM</application> program has been part of
	  FreeBSD ever since version 2.0 was released, and lives in
	  <filename>/usr/src/usr.sbin/CTM</filename> if you have a copy of the
	  source online.</para>
	    
	<para>If you are running a pre-2.0 version of FreeBSD, you can fetch
	  the current <application>CTM</application> sources directly
	  from:</para>
	    
	<para><ulink
	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm</ulink></para>
	    
	<para>The &ldquo;deltas&rdquo; you feed <application>CTM</application>
	  can be had two ways, FTP or e-mail.  If you have general FTP access
	  to the Internet then the following FTP sites support access to
	  <application>CTM</application>:</para>
	    
	<para><ulink
	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM">ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM</ulink></para>
	    
	<para>or see section <link linkend="mirrors-ctm">mirrors</link>.</para>
	
	<para>FTP the relevant directory and fetch the
	  <filename>README</filename> file, starting from there.</para>
	    
	<para>If you may wish to get your deltas via email:</para>
	    
	<para>Send email to &a.majordomo; to subscribe to one of the
	  <application>CTM</application> distribution lists.
	  &ldquo;ctm-cvs-cur&rdquo; supports the entire cvs tree.
	  &ldquo;ctm-src-cur&rdquo; supports the head of the development
	  branch.  &ldquo;ctm-src-2_2&rdquo; supports the 2.2 release branch,
	  etc.  (If you do not know how to subscribe yourself using majordomo,
	  send a message first containing the word <literal>help</literal>
	  &mdash; it will send you back usage instructions.)</para>
	    
	<para>When you begin receiving your <application>CTM</application>
	  updates in the mail, you may use the <command>ctm_rmail</command>
	  program to unpack and apply them.  You can actually use the
	  <command>ctm_rmail</command> program directly from a entry in
	  <filename>/etc/aliases</filename> if you want to have the process
	  run in a fully automated fashion.  Check the
	  <command>ctm_rmail</command> man page for more details.</para>

	<note>
	  <para>No matter what method you use to get the
	    <application>CTM</application> deltas, you should subscribe to the
	    <email>ctm-announce@FreeBSD.org</email> mailing list.  In the
	    future, this will be the only place where announcements concerning
	    the operations of the <application>CTM</application> system will
	    be posted.  Send an email to &a.majordomo; with a single line of
	    <literal>subscribe ctm-announce</literal> to get added to the
	    list.</para>
	</note>
      </sect3>
      
      <sect3>
	<title>Starting off with <application>CTM</application> for the first
	  time</title>
	    
	<para>Before you can start using <application>CTM</application>
	  deltas, you will need to get to a starting point for the deltas
	  produced subsequently to it.</para>
	    
	<para>First you should determine what you already have.  Everyone can
	  start from an &ldquo;empty&rdquo; directory.  You must use an
	  initial &ldquo;Empty&rdquo delta to start off your
	  <application>CTM</application> supported tree.  At some point it is
	  intended that one of these &ldquo;started&rdquo; deltas be
	  distributed on the CD for your convenience.  This does not currently
	  happen however.</para>

	<para>However, since the trees are many tens of megabytes, you should
	  prefer to start from something already at hand.  If you have a
	  RELEASE CD, you can copy or extract an initial source from it.  This
	  will save a significant transfer of data.</para>
	    
	<para>You can recognize these &ldquo;starter&rdquo; deltas by the
	  <literal>X</literal> appended to the number
	  (<filename>src-cur.3210XEmpty.gz</filename> for instance).  The
	  designation following the <filename>X</filename> corresponds to the
	  origin of your initial &ldquo;seed&rdquo;.
	  <filename>Empty</filename> is an empty directory.  As a rule a base
	  transition from <filename>Empty</filename> is produced every 100
	  deltas.  By the way, they are large! 25 to 30 Megabytes of
	  <command>gzip</command>'ed data is common for the
	  <filename>XEmpty</filename> deltas.</para>
	    
	<para>Once you've picked a base delta to start from, you will also
	  need all deltas with higher numbers following it.</para>
      </sect3>
      
      <sect3>
	<title>Using <application>CTM</application> in your daily life</title>
	
	<para>To apply the deltas, simply say:</para>
	
	<screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput>
&prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen>
	      
	<para><application>CTM</application> understands deltas which have
	  been put through <command>gzip</command>, so you do not need to
	  gunzip them first, this saves disk space.</para>
	    
	<para>Unless it feels very secure about the entire process,
	  <application>CTM</application> will not touch your tree.  To verify
	  a delta you can also use the <option>-c</option> flag and
	  <application>CTM</application> will not actually touch your tree; it
	  will merely verify the integrity of the delta and see if it would
	  apply cleanly to your current tree.</para>
	    
	<para>There are other options to <application>CTM</application> as
	  well, see the manual pages or look in the sources for more
	  information.</para>
	    
	<para>I would also be very happy if somebody could help with the
	  &ldquo;user interface&rdquo; portions, as I have realized that I
	  cannot make up my mind on what options should do what, how and
	  when...</para>
	    
	<para>That's really all there is to it.  Every time you get a new
	  delta, just run it through <application>CTM</application> to keep
	  your sources up to date.</para>
	    
	<para>Do not remove the deltas if they are hard to download again. You
	  just might want to keep them around in case something bad happens.
	  Even if you only have floppy disks, consider using
	  <command>fdwrite</command> to make a copy.</para>
      </sect3>
      
      <sect3>
	<title>Keeping your local changes</title>
	
	<para>As a developer one would like to experiment with and change
	  files in the source tree.  <application>CTM</application> supports
	  local modifications in a limited way: before checking for the
	  presence of a file <filename>foo</filename>, it first looks for
	  <filename>foo.ctm</filename>.  If this file exists, CTM will operate
	  on it instead of <filename>foo</filename>.</para>
	    
	<para>This behaviour gives us a simple way to maintain local changes:
	  simply copy the files you plan to modify to the corresponding file
	  names with a <filename>.ctm</filename> suffix.  Then you can freely
	  hack  the code, while CTM keeps the <filename>.ctm</filename> file
	  up-to-date.</para>
      </sect3>
      
      <sect3>
	<title>Other interesting <application>CTM</application> options</title>
	
	<sect4>
	  <title>Finding out exactly what would be touched by an
	    update</title>
	      
	  <para>You can determine the list of changes that
	    <application>CTM</application> will make on your source repository
	    using the <option>-l</option> option to
	    <application>CTM</application>.</para>
	      
	  <para>This is useful if you would like to keep logs of the changes,
	    pre- or post- process the modified files in any manner, or just
	    are feeling a tad paranoid <!-- smiley -->:-).</para>
	</sect4>
	
	<sect4>
	  <title>Making backups before updating</title>
	  
	  <para>Sometimes you may want to backup all the files that would be
	    changed by a <application>CTM</application> update.</para>
	      
	  <para>Specifying the <option>-B backup-file</option> option causes
	    <application>CTM</application> to backup all files that would be
	    touched by a given <application>CTM</application> delta to
	    <filename>backup-file</filename>.</para>
	</sect4>
	
	<sect4>
	  <title>Restricting the files touched by an update</title>
	  
	  <para>Sometimes you would be interested in restricting the scope of
	    a given <application>CTM</application> update, or may be
	    interested in extracting just a few files from a sequence of
	    deltas.</para>
	      
	  <para>You can control the list of files that
	    <application>CTM</application> would operate on by specifying
	    filtering regular expressions using the <option>-e</option> and
	    <option>-x</option> options.</para>
	      
	  <para>For example, to extract an up-to-date copy of
	    <filename>lib/libc/Makefile</filename> from your collection of
	    saved CTM deltas, run the commands:</para>
		
	  <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput>
&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen>
		
	  <para>For every file specified in a <application>CTM</application>
	    delta, the <option>-e</option> and <option>-x</option> options are
	    applied in the order given on the command line.  The file is
	    processed by <application>CTM</application> only if it is marked
	    as eligible after all the <option>-e</option> and
	    <option>-x</option> options are applied to it.</para>
	</sect4>
      </sect3>
      
      <sect3>
	<title>Future plans for <application>CTM</application></title>
	
	<para>Tons of them:</para>
	
	<itemizedlist>
	  <listitem>
	    <para>Use some kind of authentication into the CTM system, so as
	      to allow detection of spoofed CTM updates.</para>
	  </listitem>
	  
	  <listitem>
	    <para>Clean up the options to <application>CTM</application>, they
	      became confusing and counter intuitive.</para>
	  </listitem>
	</itemizedlist>
	
	<para>The bad news is that I am very busy, so any help in doing this
	  will be most welcome.  And do not forget to tell me what you want
	  also...</para>
      </sect3>
      
      <sect3>
	<title>Miscellaneous stuff</title>
	
	<para>All the &ldquo;DES infected&rdquo; (e.g. export controlled)
	  source is not included.  You will get the
	  &ldquo;international&rdquo; version only. If sufficient interest
	  appears, we will set up a <literal>sec-cur</literal> sequence too.
	  There is a sequence of deltas for the <literal>ports</literal>
	  collection too, but interest has not been all that high yet. Tell me
	  if you want an email list for that too and we will consider setting
	  it up.</para>
      </sect3>
      
      <sect3>
	<title>Thanks!</title>
	
	<variablelist>
	  <varlistentry>
	    <term>&a.bde;</term>

	    <listitem>
	      <para>for his pointed pen and invaluable comments.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>&a.sos;</term>
	    
	    <listitem>
	      <para>for patience.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>Stephen McKay</term>
	    
	    <listitem>
	      <para>wrote <command>ctm_[rs]mail</command>, much
		appreciated.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>&a.jkh;</term>
	    
	    <listitem>
	      <para>for being so stubborn that I had to make it better.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>All the users</term>
	    
	    <listitem>
	      <para>I hope you like it...</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
    </sect2>
    
    <sect2 id="cvsup">
      <title><application>CVSup</application></title>
      
      <para><emphasis>Contributed by &a.jdp;</emphasis>.</para>
      
      <sect3 id="cvsup-intro">
	<title>Introduction</title>
	
	<para><application>CVSup</application> is a software package for
	  distributing and updating source trees from a master CVS repository
	  on a remote server host.  The FreeBSD sources are maintained in a
	  CVS repository on a central development machine in California.  With
	  <application>CVSup</application>, FreeBSD users can easily keep
	  their own source trees up to date.</para>
	    
	<para><application>CVSup</application> uses the so-called
	  <emphasis>pull</emphasis> model of updating.  Under the pull model,
	  each client asks the server for updates, if and when they are
	  wanted.  The server waits passively for update requests from its
	  clients.  Thus all updates are instigated by the client.  The server
	  never sends unsolicited updates.  Users must either run the
	  <application>CVSup</application> client manually to get an update,
	  or they must set up a <command>cron</command> job to run it
	  automatically on a regular basis.</para>
	    
	<para>The term <application>CVSup</application>, capitalized just so,
	  refers to the entire software package.  Its main components are the
	  client <command>cvsup</command> which runs on each user's machine,
	  and the server <command>cvsupd</command> which runs at each of the
	  FreeBSD mirror sites.</para>
	    
	<para>As you read the FreeBSD documentation and mailing lists, you may
	  see references to <application>sup</application>.
	  <application>Sup</application> was the predecessor of
	  <application>CVSup</application>, and it served a similar purpose.
	  <application>CVSup</application> is in used in much the same way as
	  sup and, in fact, uses configuration files which are
	  backward-compatible with <command>sup</command>'s.
	  <application>Sup</application> is no longer used in the FreeBSD
	  project, because <application>CVSup</application> is both faster and
	  more flexible.</para>
      </sect3>
      
      <sect3 id="cvsup-install">
	<title>Installation</title>
	
	<para>The easiest way to install <application>CVSup</application> if
	  you are running FreeBSD 2.2 or later is to use either <ulink
	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports-current/net/cvsup.tar">the
	    port</ulink> from the FreeBSD <link linkend="ports">ports
	    collection</link> or the corresponding <ulink
	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/packages-current/net/cvsup-16.0.tgz">binary
	    package</ulink>, depending on whether you prefer to roll your own
	  or not.</para>
	    
	<para>If you are running FreeBSD-2.1.6 or 2.1.7, you unfortunately
	  cannot use the binary package versions due to the fact that they
	  require a version of the C library that does not yet exist in
	  FreeBSD-2.1.{6,7}.  You can easily use <ulink
	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports-current/net/cvsup.tar">the
	    port</ulink>, however, just as with FreeBSD 2.2.  Simply unpack
	  the tar file, cd to the cvsup subdirectory and type <command>make
	    install</command>.</para>
	    
	<para>Because <application>CVSup</application> is written in <ulink
	    URL="http://www.research.digital.com/SRC/modula-3/html/home.html">Modula-3</ulink>,
	  both the package and the port require that the Modula-3 runtime
	  libraries be installed.  These are available as the <ulink
	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/ports-current/lang/modula-3-lib.tar">lang/modula-3-lib</ulink> port and the <ulink URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/packages-current/lang/modula-3-lib-3.6.tgz">lang/modula-3-lib-3.6</ulink> package.
	  If you follow the same directions as for <command>cvsup</command>,
	  these libraries will be compiled and/or installed automatically when
	  you install the <application>CVSup</application> port or
	  package.</para>
	    
	<para>The Modula-3 libraries are rather large, and fetching and
	  compiling them is not an instantaneous process.  For that reason, a
	  third option is provided.  You can get <emphasis>statically
	    linked</emphasis> FreeBSD executables for
	  <application>CVSup</application> from the USA distribution
	  site:</para>
	    
	<itemizedlist>
	  <listitem>
	    <para><ulink
		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup-bin-16.0.tar.gz">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup-bin-16.0.tar.gz</ulink> (client including GUI).</para>
	  </listitem>
	  
	  <listitem>
	    <para><ulink
		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-16.0.tar.gz">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsup.nogui-bin-16.0.tar.gz</ulink> (client without GUI).</para>
	  </listitem>
	  
	  <listitem>
	    <para><ulink
		URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupd-bin-16.0.tar.gz">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CVSup/cvsupd-bin-16.0.tar.gz</ulink> (server).</para>
	  </listitem>
	</itemizedlist>
	
	<para>as well as from the many FreeBSD <link linkend="mirrors-ftp">FTP
	    mirror sites</link> around the world.</para>
	
	<para>Most users will need only the client.  These executables are
	  entirely self-contained, and they will run on any version of FreeBSD
	  from FreeBSD-2.1.0 to FreeBSD-current.</para>
	    
	<para>In summary, your options for installing CVSup are:</para>
	
	<itemizedlist>
	  <listitem>
	    <para>FreeBSD-2.2 or later:		static binary, port, or
	      package</para>
	  </listitem>
	  
	  <listitem>
	    <para>FreeBSD-2.1.6, 2.1.7:		static binary or port</para>
	  </listitem>
	  
	  <listitem>
	    <para>FreeBSD-2.1.5 or earlier:	static binary</para>
	  </listitem>
	</itemizedlist>
      </sect3>
      
      <sect3 id="cvsup-config">
	<title>CVSup Configuration</title>
	
	<para><application>CVSup</application>'s operation is controlled by a
	  configuration file called the <filename>supfile</filename>.
	  Beginning with FreeBSD-2.2, there are some sample
	  <filename>supfiles</filename> in the directory <ulink
	    URL="file:/usr/share/examples/cvsup">/usr/share/examples/cvsup</ulink>.
	  These examples are also available from <ulink
	    URL="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/src/share/examples/cvsup/</ulink> if you are on a pre-2.2 system.</para>
	
	<para>The information in a <filename>supfile</filename> answers the
	  following questions for cvsup:</para>
		    
	<itemizedlist>
	  <listitem>
	    <para><link linkend="cvsup-config-files">Which files do you want
		to receive?</link></para>
	  </listitem>
	  
	  <listitem>
	    <para><link linkend="cvsup-config-vers">Which versions of them do
		you want?</link></para>
	  </listitem>
	  
	  <listitem>
	    <para><link linkend="cvsup-config-where">Where do you want to get
		them from?</link></para>
	  </listitem>
	  
	  <listitem>
	    <para><link linkend="cvsup-config-dest">Where do you want to put
		them on your own machine?</link></para>
	  </listitem>
	  
	  <listitem>
	    <para><link linkend="cvsup-config-status">Where do you want to put
		your status files?</link></para>
	  </listitem>
	</itemizedlist>
	
	<para>In the following sections, we will construct a typical
	  <filename>supfile</filename> by answering each of these questions in
	  turn.  First, we describe the overall structure of a
	  <filename>supfile</filename>.</para>
	    
	<para>A <filename>supfile</filename> is a text file.  Comments begin
	  with <literal>#</literal> and extend to the end of the line.  Lines
	  that are blank and lines that contain only comments are
	  ignored.</para>
	    
	<para>Each remaining line describes a set of files that the user
	  wishes to receive.  The line begins with the name of a
	  &ldquo;collection&rdquo;, a logical grouping of files defined by the
	  server. The name of the collection tells the server which files you
	  want.  After the collection name come zero or more fields, separated
	  by white space.  These fields answer the questions listed above.
	  There are two types of fields: flag fields and value fields.  A flag
	  field consists of a keyword standing alone, e.g.,
	  <literal>delete</literal> or <literal>compress</literal>.  A value
	  field also begins with a keyword, but the keyword is followed
	  without intervening white space by <literal>=</literal> and a second
	  word.  For example, <literal>release=cvs</literal> is a value
	  field.</para>
	    
	<para>A <filename>supfile</filename> typically specifies more than one
	  collection to receive.  One way to structure a
	  <filename>supfile</filename> is to specify all of the relevant
	  fields explicitly for each collection.  However, that tends to make
	  the <filename>supfile</filename> lines quite long, and it is
	  inconvenient because most fields are the same for all of the
	  collections in a <filename>supfile</filename>.
	  <application>CVSup</application> provides a defaulting mechanism to
	  avoid these problems.  Lines beginning with the special
	  pseudo-collection name <literal>*default</literal> can be used to
	  set flags and values which will be used as defaults for the
	  subsequent collections in the <filename>supfile</filename>.  A
	  default value can be overridden for an individual collection, by
	  specifying a different value with the collection itself. Defaults
	  can also be changed or augmented in mid-supfile by additional
	  <literal>*default</literal> lines.</para>
	    
	<para>With this background, we will now proceed to construct a
	  <filename>supfile</filename> for receiving and updating the main
	  source tree of <link
	    linkend="current">FreeBSD-current</link>.</para>
	
	<itemizedlist>
	  <listitem>
	    <para>Which files do you want to receive?<anchor
		id="cvsup-config-files"></para>
		  
	    <para>The files available via <application>CVSup</application> are
	      organized into named groups called &ldquo;collections&rdquo;.
	      The collections that are available are described <link
		linkend="cvsup-collec">here</link>.  In this example, we wish
	      to receive the entire main source tree for the FreeBSD system.
	      There is a single large collection <literal>src-all</literal>
	      which will give us all of that, except the export-controlled
	      cryptography support.  Let us assume for this example that we
	      are in the USA or Canada.  Then we can get the cryptography code
	      with one additional collection, <literal>cvs-crypto</literal>.
	      As a first step toward constructing our
	      <filename>supfile</filename>, we simply list these collections,
	      one per line:</para>
		  
	    <programlisting>
src-all
cvs-crypto</programlisting>
	  </listitem>
		
	  <listitem>
	    <para>Which version(s) of them do you want?<anchor
		id="cvsup-config-vers"></para>
		  
	    <para>With <application>CVSup</application>, you can receive
	      virtually any version of the sources that ever existed.  That is
	      possible because the cvsupd server works directly from the CVS
	      repository, which contains all of the versions.  You specify
	      which one of them you want using the <literal>tag=</literal> and
	      <option>date=</option> value fields.</para>

	    <warning>
	      <para>Be very careful to specify any <literal>tag=</literal>
		fields correctly.  Some tags are valid only for certain
		collections of files.  If you specify an incorrect or
		misspelled tag, CVSup will delete files which you probably do
		not want deleted.  In particular, use <emphasis>only
		</emphasis> <literal>tag=.</literal> for the
		<literal>ports-*</literal> collections.</para>
	    </warning>
		
	    <para>The <literal>tag=</literal> field names a symbolic tag in
	      the repository.  There are two kinds of tags, revision tags and
	      branch tags.  A revision tag refers to a specific revision.  Its
	      meaning stays the same from day to day.  A branch tag, on the
	      other hand, refers to the latest revision on a given line of
	      development, at any given time.  Because a branch tag does not
	      refer to a specific revision, it may mean something different
	      tomorrow than it means today.</para>

	    <para>Here are the branch tags that users might be interested
	      in:</para>
	    
	    <variablelist>
	      <varlistentry>
		<term>tag=.</term>

		<listitem>
		  <para>The main line of development, also known as
		    FreeBSD-current.</para>

		  <note>
		    <para>The <literal>.</literal> is not punctuation; it is
		      the name of the tag.  Valid for all collections.</para>
		  </note>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>RELENG_3</term>

		<listitem>
		  <para>The line of development for FreeBSD-3.x, also known as
		    FreeBSD-stable.  Not valid for the ports
		    collection.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>RELENG_2_2</term>
		
		<listitem>
		  <para>The line of development for FreeBSD-2.2.x, also known
		    as 2.2-stable.  Not valid for the ports collection.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_1_0</term>
		
		<listitem>
		  <para>The line of development for FreeBSD-2.1.x - this
		    branch is largely obsolete.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	    
	    <para>Here are the revision tags that users might be interested
	      in:</para>
		  
	    <variablelist>
	      <varlistentry>

              <term>tag=RELENG_3_2_0_RELEASE</term>
                      
                <listitem>
                  <para>FreeBSD-3.2.  Not valid for the ports-*
                  collections.</para>
                </listitem>
              </varlistentry>
        
              <varlistentry>
		<term>tag=RELENG_3_1_0_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-3.1.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_3_0_0_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-3.0.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_2_8_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.2.8.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_2_7_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.2.7.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_2_6_RELEASE</term>

		<listitem>
		  <para>FreeBSD-2.2.6.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_2_5_RELEASE</term>
			
		<listitem>
		  <para>FreeBSD-2.2.5.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_2_2_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.2.2.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_2_1_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.2.1.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_2_0_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.2.0.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_1_7_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.1.7.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_1_6_1_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.1.6.1.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_1_6_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.1.6.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_1_5_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.1.5.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	      
	      <varlistentry>
		<term>tag=RELENG_2_1_0_RELEASE</term>
		
		<listitem>
		  <para>FreeBSD-2.1.0.  Not valid for the ports-*
		    collections.</para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	    
	    <warning>
	      <para>Be very careful to type the tag name exactly as shown.
		<application>CVSup</application> cannot distinguish between
		valid and invalid tags.  If you misspell the tag,
		<application>CVSup</application> will behave as though you had
		specified a valid tag which happens to refer to no files at
		all.  It will delete your existing sources in that
		case.</para>
	    </warning>
	    
	    <para>When you specify a branch tag, you normally receive the
	      latest versions of the files on that line of development.  If
	      you wish to receive some past version, you can do so by
	      specifying a date with the <option>date=</option> value field.
	      The &man.cvsup.1; manual page explains how to do
	      that.</para>

	    <para>For our example, we wish to receive FreeBSD-current. We add
	      this line at the beginning of our
	      <filename>supfile</filename>:</para>
		  
	    <programlisting>
*default tag=.</programlisting>

	    <para>There is an important special case that comes into play if
	      you specify neither a <literal>tag=</literal> field nor a
	      <literal>date=</literal> field.  In that case, you receive the
	      actual RCS files directly from the server's CVS repository,
	      rather than receiving a particular version.  Developers
	      generally prefer this mode of operation.  By maintaining a copy
	      of the repository itself on their systems, they gain the ability
	      to browse the revision histories and examine past versions of
	      files.  This gain is achieved at a large cost in terms of disk
	      space, however.</para>
	  </listitem>
	  
	  <listitem>
	    <para>Where do you want to get them from?<anchor
		id="cvsup-config-where"></para>
		  
	    <para>We use the <literal>host=</literal> field to tell
	      <command>cvsup</command> where to obtain its updates.  Any of
	      the <link linkend="mirrors-cvsup">CVSup mirror sites</link> will
	      do, though you should try to select one that is close to you in
	      cyberspace.  In this example we will use a fictional FreeBSD
	      distribution site, <hostid
		role="fqdn">cvsup666.FreeBSD.org</hostid>:</para>
		  
	    <programlisting>
*default host=cvsup666.FreeBSD.org</programlisting>

	    <para>You will need to change the host to one that actually exists
	      before running CVSup.  On any particular run of
	      <command>cvsup</command>, you can override the host  setting on
	      the command line, with <option>-h
		<replaceable>hostname</replaceable></option>.</para>
	  </listitem>
	  
	  <listitem>
	    <para>Where do you want to put them on your own machine?<anchor
		id="cvsup-config-dest"></para>
		  
	    <para>The <literal>prefix=</literal> field tells
	      <command>cvsup</command> where to put the files it receives.  In
	      this example, we will put the source files directly into our
	      main source tree, <filename>/usr/src</filename>.  The
	      <filename>src</filename> directory is already implicit in the
	      collections we have chosen to receive, so this is the correct
	      specification:</para>
		  
	    <programlisting>
*default prefix=/usr</programlisting>
	  </listitem>
		
	  <listitem>
	    <para>Where should <command>cvsup</command> maintain its status
	      files?<anchor id="cvsup-config-status"></para>
		  
	    <para>The cvsup client maintains certain status files in what is
	      called the &ldquo;base&rdquo; directory.  These files help
	      <application>CVSup</application> to work more efficiently, by
	      keeping track of which updates you have already received.  We
	      will use the standard base directory,
	      <filename>/usr/local/etc/cvsup</filename>:</para>
		  
	    <programlisting>
*default base=/usr/local/etc/cvsup</programlisting>

	    <para>This setting is used by default if it is not specified in
	      the <filename>supfile</filename>, so we actually do not need the
	      above line.</para>

	    <para>If your base directory does not already exist, now would be
	      a good time to create it.  The <command>cvsup</command> client
	      will refuse to run if the base directory does not exist.</para>
	  </listitem>
		
	  <listitem>
	    <para>Miscellaneous <filename>supfile</filename> settings:</para>
	    
	    <para>There is one more line of boiler plate that normally needs
	      to be present in the <filename>supfile</filename>:</para>
		  
	    <programlisting>
*default release=cvs delete use-rel-suffix compress</programlisting>

	    <para><literal>release=cvs</literal> indicates that the server
	      should get its information out of the main FreeBSD CVS
	      repository.  This is virtually always the case, but there are
	      other possibilities which are beyond the scope of this
	      discussion.</para>

	    <para><literal>delete</literal> gives
	      <application>CVSup</application> permission to delete files.
	      You should always specify this, so that
	      <application>CVSup</application> can keep your source tree fully
	      up to date.  <application>CVSup</application> is careful to
	      delete only those files for which it is responsible.  Any extra
	      files you happen to have will be left strictly alone.</para>

	    <para><literal>use-rel-suffix</literal> is ... arcane.  If you
	      really want to know about it, see the &man.cvsup.1; manual page.
	      Otherwise, just specify it and do not worry about it.</para>

	    <para><literal>compress</literal> enables the use of gzip-style
	      compression on the communication channel.  If your network link
	      is T1 speed or faster, you probably should not use compression.
	      Otherwise, it helps substantially.</para>
	  </listitem>
	  
	  <listitem>
	    <para>Putting it all together:</para>
	    
	    <para>Here is the entire <filename>supfile</filename> for our
	      example:</para>
		  
	    <programlisting>
*default tag=.
*default host=cvsup666.FreeBSD.org
*default prefix=/usr
*default base=/usr/local/etc/cvsup
*default release=cvs delete use-rel-suffix compress

src-all
cvs-crypto</programlisting>
	  </listitem>
	</itemizedlist>
      </sect3>
      
      <sect3>
	<title>Running <application>CVSup</application></title>
	
	<para>You are now ready to try an update.  The command line for doing
	  this is quite simple:</para>
	    
	<screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen>
	    
	<para>where <filename><replaceable>supfile</replaceable></filename> is
	  of course the name of the supfile you have just created.  Assuming
	  you are running under X11, <command>cvsup</command> will display a
	  GUI window with some buttons to do the usual things.  Press the
	  &ldquo;go&rdquo; button, and watch it run.</para>
	    
	<para>Since you are updating your actual <filename>/usr/src</filename>
	  tree in this example, you will need to run the program as
	  <username>root</username> so that <command>cvsup</command> has the
	  permissions it needs to update your files.  Having just created your
	  configuration file, and having never used this program before, that
	  might understandably make you nervous. There is an easy way to do a
	  trial run without touching your precious files.  Just create an
	  empty directory somewhere convenient, and name it as an extra
	  argument on the command line:</para>
	
	<screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput>
&prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen>
	    
	<para>The directory you specify will be used as the destination
	  directory for all file updates.  <application>CVSup</application>
	  will examine your usual files in <filename>/usr/src</filename>, but
	  it will not modify or delete any of them.  Any file updates will
	  instead land in <filename>/var/tmp/dest/usr/src</filename>.
	  <application>CVSup</application> will also leave its base directory
	  status files untouched when run this way.  The new versions of those
	  files will be written into the specified directory.  As long as you
	  have read access to <filename>/usr/src</filename>, you do not even
	  need to be root to perform this kind of trial run.</para>
	    
	<para>If you are not running X11 or if you just do not like GUIs, you
	  should add a couple of options to the command line when you run
	  cvsup:</para>
	    
	<screen>&prompt.root; <userinput>cvsup -g -L 2 supfile</userinput></screen>
	    
	<para>The <option>-g</option> tells cvsup not to use its GUI.  This is
	  automatic if you are not running X11, but otherwise you have to
	  specify it.</para>
	    
	<para>The <option>-L 2</option> tells cvsup to print out the details
	  of all the file updates it is doing.  There are three levels of
	  verbosity, from <option>-L 0</option> to <option>-L 2</option>.  The
	  default is 0, which means total silence except for error
	  messages.</para>
	    
	<para>There are plenty of other options available.  For a brief list
	  of them, type <command>cvsup -H</command>.  For more detailed
	  descriptions, see the manual page.</para>
	
	<para>Once you are satisfied with the way updates are working, you can
	  arrange for regular runs of cvsup using &man.cron.8;.
	  Obviously, you should not let cvsup use its GUI when running it from
	  cron.</para>
      </sect3>
      
      <sect3 id="cvsup-collec">
	<title><application>CVSup</application> File Collections</title>
	    
	<para>The file collections available via
	  <application>CVSup</application> are organized hierarchically.
	  There are a few large collections, and they are divided into smaller
	  sub-collections.  Receiving a large collection is equivalent to
	  receiving each of its sub-collections.  The hierarchical
	  relationships among collections are reflected by the use of
	  indentation in the list below.</para>
	    
	<para>The most commonly used collections are
	  <literal>src-all</literal>, <literal>cvs-crypto</literal>, and
	  <literal>ports-all</literal>.  The other collections are used only
	  by small groups of people for specialized purposes, and some mirror
	  sites may not carry all of them.</para>
	
	<variablelist>
	  <varlistentry>
	    <term><literal>cvs-all release=cvs</literal></term>

	    <listitem>
	      <para>The main FreeBSD CVS repository, excluding the
		export-restricted cryptography code.</para>
		    
	      <variablelist>
		<varlistentry>
		  <term><literal>distrib release=cvs</literal></term>
		  
		  <listitem>
		    <para>Files related to the distribution and mirroring of
		      FreeBSD.</para>
		  </listitem>
		</varlistentry>
		
		<varlistentry>
		  <term><literal>doc-all release=cvs</literal></term>
		  
		  <listitem>
		    <para>Sources for the FreeBSD handbook and other
		      documentation.</para>
		  </listitem>
		</varlistentry>
		
		<varlistentry>
		  <term><literal>ports-all release=cvs</literal></term>
			  
		  <listitem>
		    <para>The FreeBSD ports collection.</para>
		    
		    <variablelist>
		      <varlistentry>
			<term><literal>ports-archivers
			    release=cvs</literal></term>

			<listitem>
			  <para>Archiving tools.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-astro
			    release=cvs</literal></term>
				  
			<listitem>
			  <para>Astronomical ports.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-audio
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Sound support.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-base release=cvs</literal></term>
			
			<listitem>
			  <para>Miscellaneous files at the top of
			    /usr/ports.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-benchmarks
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Benchmarks.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-biology
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Biology.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-cad release=cvs</literal></term>
			
			<listitem>
			  <para>Computer aided design tools.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-chinese
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Chinese language support.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-comms
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Communication software.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-converters
			    release=cvs</literal></term>
			
			<listitem>
			  <para>character code converters.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-databases
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Databases.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal></literal>ports-deskutils
			  release=cvs</term>
			
			<listitem>
			  <para>Things that used to be on the desktop before
			    computers were invented.</para>
			  </listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-devel
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Development utilities.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-editors
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Editors.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-emulators
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Emulators for other operating systems.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-games
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Games.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-german
			    release=cvs</literal></term>
			
			<listitem>
			  <para>German language support.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-graphics
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Graphics utilities.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-japanese
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Japanese language support.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-korean
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Korean language support.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-lang release=cvs</literal></term>
			
			<listitem>
			  <para>Programming languages.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-mail release=cvs</literal></term>
			
			<listitem>
			  <para>Mail software.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-math release=cvs</literal></term>
			
			<listitem>
			  <para>Numerical computation software.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-mbone
			    release=cvs</literal></term>
			
			<listitem>
			  <para>MBone applications.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-misc release=cvs</literal></term>
			
			<listitem>
			  <para>Miscellaneous utilities.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-net release=cvs</literal></term>
			
			<listitem>
			  <para>Networking software.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-news release=cvs</literal></term>
				  
			<listitem>
			  <para>USENET news software.</para>
			</listitem>
		      </varlistentry>

                      <varlistentry>
                        <term><literal>ports-palm
                          release=cvs</literal></term>
                              
                        <listitem>
                          <para>Software support for 3Com Palm(tm) series.</para>
                        </listitem>
                      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-plan9
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Various programs from Plan9.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-print
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Printing software.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-russian
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Russian language support.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-security
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Security utilities.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-shells
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Command line shells.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-sysutils
			    release=cvs</literal></term>

			<listitem>
			  <para>System utilities.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-textproc
			    release=cvs</literal></term>
			
			<listitem>
			  <para>text processing utilities (does not include
			    desktop publishing).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-vietnamese
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Vietnamese language support.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-www release=cvs</literal></term>
				  
			<listitem>
			  <para>Software related to the World Wide Web.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-x11 release=cvs</literal></term>
				  
			<listitem>
			  <para>Ports to support the X window system.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-x11-clocks
			    release=cvs</literal></term>
			
			<listitem>
			  <para>X11 clocks.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-x11-fm
			    release=cvs</literal></term>
			
			<listitem>
			  <para>X11 file managers.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-x11-fonts
			    release=cvs</literal></term>
			
			<listitem>
			  <para>X11 fonts and font utilities.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-x11-toolkits
			    release=cvs</literal></term>
			
			<listitem>
			  <para>X11 toolkits.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>ports-x11-wm</literal></term>
			
			<listitem>
			  <para>X11 window managers.</para>
			</listitem>
		      </varlistentry>
		    </variablelist>
		  </listitem>
		</varlistentry>
		
		<varlistentry>
		  <term><literal>src-all release=cvs</literal></term>
		  
		  <listitem>
		    <para>The main FreeBSD sources, excluding the
		      export-restricted cryptography code.</para>
			    
		    <variablelist>
		      <varlistentry>
			<term><literal>src-base release=cvs</literal></term>
			
			<listitem>
			  <para>Miscellaneous files at the top of
			    <filename>/usr/src</filename>.</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-bin release=cvs</literal></term>
				  
			<listitem>
			  <para>User utilities that may be needed in
			    single-user mode
			    (<filename>/usr/src/bin</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-contrib
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Utilities and libraries from outside the
			    FreeBSD project, used relatively unmodified
			    (<filename>/usr/src/contrib</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-etc release=cvs</literal></term>
				  
			<listitem>
			  <para>System configuration files
			    (<filename>/usr/src/etc</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-games release=cvs</literal></term>
			
			<listitem>
			  <para>Games
			    (<filename>/usr/src/games</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-gnu release=cvs</literal></term>
			
			<listitem>
			  <para>Utilities covered by the GNU Public License
			    (<filename>/usr/src/gnu</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-include
			    release=cvs</literal></term>
				  
			<listitem>
			  <para>Header files
			    (<filename>/usr/src/include</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-kerberosIV
			    release=cvs</literal></term>
				  
			<listitem>
			  <para>KerberosIV security package
			    (<filename>/usr/src/kerberosIV</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-lib release=cvs</literal></term>
				  
			<listitem>
			  <para>Libraries
			    (<filename>/usr/src/lib</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-libexec
			    release=cvs</literal></term>
			
			<listitem>
			  <para>System programs normally executed by other
			    programs
			    (<filename>/usr/src/libexec</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-release
			    release=cvs</literal></term>
			
			<listitem>
			  <para>Files required to produce a FreeBSD release
			    (<filename>/usr/src/release</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-sbin release=cvs</literal></term>
			
			<listitem>
			  <para>System utilities for single-user mode
			    (<filename>/usr/src/sbin</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-share release=cvs</literal></term>
			
			<listitem>
			  <para>Files that can be shared across multiple
			    systems
			    (<filename>/usr/src/share</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-sys release=cvs</literal></term>
				  
			<listitem>
			  <para>The kernel
			    (<filename>/usr/src/sys</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-tools release=cvs</literal></term>
				  
			<listitem>
			  <para>Various tools for the maintenance of FreeBSD
			    (<filename>/usr/src/tools</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-usrbin release=cvs</literal></term>
			
			<listitem>
			  <para>User utilities
			    (<filename>/usr/src/usr.bin</filename>).</para>
			</listitem>
		      </varlistentry>
		      
		      <varlistentry>
			<term><literal>src-usrsbin
			    release=cvs</literal></term>
			
			<listitem>
			  <para>System utilities
			    (<filename>/usr/src/usr.sbin</filename>).</para>
			</listitem>
		      </varlistentry>
		    </variablelist>
		  </listitem>
		</varlistentry>
		
		<varlistentry>
		  <term><literal>www release=cvs</literal></term>
			  
		  <listitem>
		    <para>The sources for the World Wide Web data.</para>
		  </listitem>
		</varlistentry>
	      </variablelist>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term><literal>cvs-crypto release=cvs</literal></term>
	    
	    <listitem>
	      <para>The export-restricted cryptography code.</para>
	      
	      <variablelist>
		<varlistentry>
		  <term><literal>src-crypto release=cvs</literal></term>

		  <listitem>
		    <para>Export-restricted utilities and libraries from
		      outside the FreeBSD project, used relatively unmodified
		      (<filename>/usr/src/crypto</filename>).</para>
		  </listitem>
		</varlistentry>
		
		<varlistentry>
		  <term><literal>src-eBones release=cvs</literal></term>
			  
		  <listitem>
		    <para>Kerberos and DES
		      (<filename>/usr/src/eBones</filename>).</para>
		  </listitem>
		</varlistentry>
		
		<varlistentry>
		  <term><literal>src-secure release=cvs</literal></term>
			  
		  <listitem>
		    <para>DES (<filename>/usr/src/secure</filename>).</para>
		  </listitem>
		</varlistentry>
	      </variablelist>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term><literal>distrib release=self</literal></term>
		  
	    <listitem>
	      <para>The CVSup server's own configuration files.  Used by CVSup
		mirror sites.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term><literal>gnats release=current</literal></term>
		  
	    <listitem>
	      <para>The GNATS bug-tracking database.</para>
	    </listitem>
	  </varlistentry>
		
	  <varlistentry>
	    <term><literal>mail-archive release=current</literal></term>
		  
	    <listitem>
	      <para>FreeBSD mailing list archive.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term><literal>www release=current</literal></term>
		  
	    <listitem>
	      <para>The installed World Wide Web data.  Used by WWW mirror
		sites.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
      
      <sect3>
	<title>For more information</title>
	
	<para>For the CVSup FAQ and other information about CVSup, see <ulink
	    url="http://www.polstra.com/projects/freeware/CVSup/">The CVSup
	    Home Page</ulink>.</para>

	<para>Most FreeBSD-related discussion of
	  <application>CVSup</application> takes place on the &a.hackers;.
	  New versions of the software are announced there, as well as on the
	  &a.announce;.</para>
	    
	<para>Questions and bug reports should be addressed to the author of
	  the program at <email>cvsup-bugs@polstra.com</email>.</para>
      </sect3>
    </sect2>
  </sect1>
  
  <sect1 id="makeworld">
    <title>Using <command>make world</command> to rebuild your system</title>
	
    <para><emphasis>Contributed by &a.nik;.</emphasis></para>
	
    <para>Once you have synchronised your local source tree against a
      particular version of FreeBSD (<literal>stable</literal>,
      <literal>current</literal> and so on) you must then use the source tree
      to rebuild the system.</para>
	
    <para>Currently, the best source of information on how to do that is a
      tutorial available from <ulink
	URL="http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html">http://www.nothing-going-on.demon.co.uk/FreeBSD/make-world/make-world.html</ulink>.</para>
	
    <para>A successor to this tutorial will be integrated into the
      handbook.</para>
  </sect1>
</chapter>

<!-- 
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../handbook.sgml" "part" "chapter")
     End:
-->