path: root/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml

<!--
     The FreeBSD Documentation Project

     $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml,v 1.50 2000/06/16 19:52:36 jim Exp $
-->

<chapter id="cutting-edge">
  <title>The Cutting Edge</title>

  <para><emphasis>Restructured, reorganized, and parts updated by &a.jim;
    March 2000.  Original work by &a.jkh;, &a.phk;, &a.jdp;, and &a.nik;
    with feedback from various others.</emphasis></para>

  <sect1>
    <title>Synopsis</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&mdash;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>
  
  <sect1 id="current-stable">
    <title>-CURRENT v.s.. -STABLE</title>

    <para>There are two development branches to FreeBSD; -CURRENT and
      -STABLE.  This section will explain a bit about each and describe
      how to keep your system up-to-date with each respective tree.
      -CURRENT will be discussed first, then -STABLE.</para>

    <sect2 id="current">
      <title>Staying Current with FreeBSD</title>

      <para>As you are reading this, keep in mind that -CURRENT is the
	<quote>bleeding edge</quote> of FreeBSD development and that if you
	are new to FreeBSD, you are most likely going to want to think
	twice about running it.</para>

      <sect3>
	<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>
      </sect3>

      <sect3>
	<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
	      <quote>current</quote> 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>
      </sect3>

      <sect3>
	<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 <quote>officially supported</quote> by us.
	      We do our best to help people genuinely in one of the 3
	      <quote>legitimate</quote> 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>
      </sect3>

      <sect3>
	<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 &a.cvsall; 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 the following in the body of your message:</para>

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

	    <para>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
	      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="mirrors-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 <quote>exported</quote> 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/tarred grabbing of whole trees.  e.g. you
		  see:</para>

		<screen>usr.bin/lex</screen>

		<para>You can do the following to get the whole directory
		  as a tar file:</para>

		<screen><prompt>ftp&gt;</prompt> <userinput>cd usr.bin</userinput>
<prompt>ftp&gt;</prompt> <userinput>get lex.tar</userinput></screen>
	      </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
	      <filename>Makefile</filename>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>
      </sect3>
    </sect2>
  
    <sect2 id="stable">
      <title>Staying Stable with FreeBSD</title>

      <para>If you are using FreeBSD in a production environment and want
	to make sure you have the latest fixes from the -CURRENT branch,
	you want to be running -STABLE.  This is the tree that -RELEASEs
	are branched from when we are putting together a new release.  For
	example, if you have a copy of 3.4-RELEASE, that is really just a
	<quote>snapshot</quote> from the -STABLE branch that we put on
	CDROM.  In order to get any changes merged into -STABLE after the
	-RELEASE, you need to <quote>track</quote> the -STABLE
	branch.</para>

      <sect3>
	<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>
      </sect3>

      <sect3>
	<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>
      </sect3>

      <sect3>
	<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 &a.cvsall; 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 the following in the body of your message:</para>

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

	    <para>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://releng4.FreeBSD.org/pub/FreeBSD/">ftp://releng4.FreeBSD.org/pub/FreeBSD/</ulink>
	      and install it like any other release.</para>

	    <para>If you are already running a previous release of FreeBSD
	      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="mirrors-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 <quote>exported</quote> 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/tarred grabbing of whole trees.  e.g. you
		  see:</para>

		<screen>usr.bin/lex</screen>

		<para>You can do the following to get the whole directory
		  for you as a tar file:</para>

		<screen><prompt>ftp&gt;</prompt> <userinput>cd usr.bin</userinput>
<prompt>ftp&gt;</prompt> <userinput>get lex.tar</userinput></screen>
	      </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
	    <filename>Makefile</filename> 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>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="synching">
    <title>Synchronizing Your Source</title>
    
    <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="mirrors-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 <quote>CTM deltas</quote> 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
      <quote>base delta</quote>) and rebuild it all with CTM or, with
      anoncvs, simply delete the bad bits and resync.</para>

    <para>More information about <application>Anonymous CVS</application>,
      <application>CTM</application>, and
      <application>CVSup</application> is available further down in this
      section.</para>

    <sect2 id="anoncvs">
      <title>Anonymous CVS</title>

      <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,
	  provides the well-known password <quote>anoncvs</quote> with the
	  <command>cvs login</command> command, 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="mirrors-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>:
	      :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs
	      (Use <command>cvs login</command> and enter the password
	      <quote>anoncvs</quote> when prompted.)</para>
	  </listitem>
	</itemizedlist>

	<para>Since CVS allows one to <quote>check out</quote> 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 (keep in mind that the only tags valid for the <link
	  linkend="ports">ports collection</link> is
	  <literal>HEAD</literal>).</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_4</term>

	    <listitem>
	      <para>The line of development for FreeBSD-4.X, also known
		as FreeBSD-STABLE.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_3</term>

	    <listitem>
	      <para>The line of development for FreeBSD-3.X, also known
		as 3.X-STABLE.</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.</para>
	    </listitem>
	  </varlistentry>
	</variablelist>

	<para>Here are the revision tags that users might be interested
	  in.  Again, none of these are valid for the ports collection
	  since the ports collection does not have multiple
	  revisions.</para>

	<variablelist>
	  <varlistentry>
	    <term>RELENG_4_0_0_RELEASE</term>

	    <listitem>
	      <para>FreeBSD 4.0.</para>
	    </listitem>
	  </varlistentry>
	  
	  <varlistentry>
	    <term>RELENG_3_4_0_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-3.4.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_3_3_0_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-3.3.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
            <term>RELENG_3_2_0_RELEASE</term>

            <listitem>
              <para>FreeBSD-3.2.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
	    <term>RELENG_3_1_0_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-3.1.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_3_0_0_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-3.0.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_8_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-2.2.8.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_7_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-2.2.7.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_6_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-2.2.6.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_5_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-2.2.5.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_2_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-2.2.2.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_1_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-2.2.1.</para>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>RELENG_2_2_0_RELEASE</term>

	    <listitem>
	      <para>FreeBSD-2.2.0.</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 :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
&prompt.user; <userinput>cvs login</userinput>
<emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
&prompt.user; <userinput>cvs co ls</userinput>
&prompt.user; <userinput>cvs release -d ls</userinput>
&prompt.user; <userinput>cvs logout</userinput>
	  </screen>
	</example>

	<example>
	  <title>Checking out the version of &man.ls.1; in the 3.X-STABLE
	    branch:</title>
	    
	  <screen>
&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
&prompt.user; <userinput>cvs login</userinput>
<emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
&prompt.user; <userinput>cvs co -rRELENG_3 ls</userinput>
&prompt.user; <userinput>cvs release -d ls</userinput>
&prompt.user; <userinput>cvs logout</userinput>
	  </screen>
	</example>

	<example>
	  <title>Creating a list of changes (as unified diffs) to &man.ls.1;</title>

	  <screen>
&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
&prompt.user; <userinput>cvs login</userinput>
<emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
&prompt.user; <userinput>cvs rdiff -u -rRELENG_3_0_0_RELEASE -rRELENG_3_4_0_RELEASE ls</userinput>
&prompt.user; <userinput>cvs logout</userinput>
	  </screen>
	</example>

	<example>
	  <title>Finding out what other module names can be used:</title>

	  <screen>
&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.FreeBSD.org:/home/ncvs</userinput>
&prompt.user; <userinput>cvs login</userinput>
<emphasis>At the prompt, enter the password</emphasis> <quote>anoncvs</quote>.
&prompt.user; <userinput>cvs co modules</userinput>
&prompt.user; <userinput>more modules/modules</userinput>
&prompt.user; <userinput>cvs release -d modules</userinput>
&prompt.user; <userinput>cvs logout</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>

  </sect1>

  <sect1 id="makeworld">
    <title>Using <command>make world</command></title>

    <para>Once you have synchronized 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>

    <warning>
      <title>Take a backup</title>

      <para>I cannot stress highly enough how important it is to take a
	backup of your system <emphasis>before</emphasis> you do this.
	While remaking the world is (as long as you follow these
	instructions) an easy task to do, there will inevitably be times
	when you make mistakes, or when mistakes made by others in the
	source tree render your system unbootable.</para>

      <para>Make sure you have taken a backup.  And have a fix-it floppy to
	hand.  I have never needed to use them, and, touch wood, I never
	will, but it is always better to be safe than sorry.</para>
    </warning>

    <warning>
      <title>Subscribe to the right mailing list</title>

      <para>The -STABLE and -CURRENT FreeBSD code branches are, by their
	nature,  <emphasis>in development</emphasis>.  People that
	contribute to FreeBSD are human, and mistakes occasionally
	happen.</para>

      <para>Sometimes these mistakes can be quite harmless, just causing
	your system to print a new diagnostic warning.  Or the change may
	be catastrophic, and render your system unbootable or destroy your
	filesystems (or worse).</para>

      <para>If problems like these occur, a <quote>heads up</quote> is
        posted to  the appropriate mailing list, explaining the nature of
	the problem and which systems it affects.  And an <quote>all
	clear</quote> announcement is posted when the problem has been
	solved.</para>

      <para>If you try and track -STABLE or -CURRENT and do not read the
	<email>stable@FreeBSD.org</email> or
	<email>current@FreeBSD.org</email> mailing lists then you are
	asking for trouble.</para>
    </warning>

    <sect2>
      <title>Read <filename>/usr/src/UPDATING</filename></title>

      <para>Before you do anything else, read
	<filename>/usr/src/UPDATING</filename> (or the equivalent file
	wherever you have a copy of the source code).  This file should
	contain important information about problems you might encounter, or
	specify the order in which you might have to run certain commands.
	If <filename>UPDATING</filename> contradicts something you read here,
	<filename>UPDATING</filename> takes precedence.</para>

      <important>
	<para>Reading <filename>UPDATING</filename> is not an acceptable
	  substitute for subscribing to the correct mailing list, as described 
	  previously.  The two requirements are complementary, not
	  exclusive.</para>
      </important>
    </sect2>

    <sect2>
      <title>Check <filename>/etc/make.conf</filename></title>

      <para>Examine the files
	<filename>/etc/defaults/make.conf</filename> and
	<filename>/etc/make.conf</filename>.  The first contains some
	default defines &ndash; most of which are commented out.  To
	make use of them when you rebuild your system from source, add
	them to <filename>/etc/make.conf</filename>.  Keep in mind that
	anything to add to <filename>/etc/make.conf</filename> is also
	used every time you run <command>make</command>, so it is a good
	idea to set them to something sensible for your system.  As a
	typical user (not a FreeBSD developer), you will probably want
	to add the <makevar>CFLAGS</makevar> and
	<makevar>NOPROFILE</makevar> lines found in
	<filename>/etc/defaults/make.conf</filename>.</para>

      <para>Everything is, by default, commented out.  Uncomment those
	entries that look useful.  For a typical user (not a developer),
	you will probably want to uncomment the CFLAGS and NOPROFILE
	definitions.</para>

      <note>
	<title/Version 2.1.7 and below/

	<para>If your machine has a floating point unit (386DX, 486DX,
	  Pentium and up class machines) then you can also uncomment the
	  HAVE_FPU line.</para>

	<para>This definition was removed for version 2.2.2 and up of
	  FreeBSD.</para>
      </note>

      <para>Examine the other definitions (COPTFLAGS, NOPORTDOCS and so
	on) and decide if they are relevant to you.</para>
    </sect2>

    <sect2>
      <title>Update <filename>/etc/group</filename></title>

      <para>The <filename>/etc</filename> directory contains a large part
	of your system's configuration information, as well as scripts
	that are run at system startup.  Some of these scripts change from
	version to version of FreeBSD.</para>

      <para>Some of the configuration files are also used in the day to
	day running of the system.  In particular,
	<filename>/etc/group</filename>.</para>

      <para>There have been occasions when the installation part of
        <quote>make world</quote> has expected certain usernames or groups
	to exist.  When performing an upgrade it is likely that these
	groups did not exist. This caused problems when upgrading.</para>

      <para>The most recent example of this is when the <quote/ppp/ group
	(later renamed <quote/network/) was added.  Users had the
	installation process fail for them when parts of the
	<filename>ppp</filename> subsystem were installed using a
	non-existent (for them) group name.</para>

      <para>The solution is to examine
	<filename>/usr/src/etc/group</filename> and compare its list of
	groups with your own.  If they are any groups in the new file that
	are not in your file then copy them over.  Similarly, you should
	rename any groups in <filename>/etc/group</filename> which have
	the same GID but a different name to those in
	<filename>/usr/src/etc/group</filename>.</para>

      <tip>
	<para>If you are feeling particularly paranoid, you can check your
	  system to see which files are owned by the group you are
	  renaming or deleting.</para>

	<screen>&prompt.root; <userinput>find / -group <replaceable>GID</replaceable> -print</userinput></screen>

	<para>will show all files owned by group
	  <replaceable>GID</replaceable> (which can be either a group name
	  or a numeric group ID).</para>
      </tip>
    </sect2>

    <sect2>
      <title/Drop to single user mode/

      <para>You may want to compile the system in single user mode.  Apart
	from the obvious benefit of making things go slightly faster,
	reinstalling the system will touch a lot of important system
	files, all the standard system binaries, libraries, include files
	and so on.  Changing these on a  running system (particularly if
	you have active users on their at the time) is asking for
	trouble.</para>

      <para>That said, if you are confident, you can omit this
	step.</para>

      <note>
	<title>Version 2.2.5 and above</title>

	<para>As described in more detail below, versions 2.2.5 and above
	  of FreeBSD have separated the building process from the
	  installing process.  You can therefore
	  <emphasis>build</emphasis> the new system in multi-user mode,
	  and then drop to single user mode to do the installation.</para>
      </note>

      <para>As the superuser, you can execute</para>

      <screen>&prompt.root; <userinput/shutdown now/</screen>

      <para>from a running system, which will drop it to single user
	mode.</para>

      <para>Alternatively, reboot the system, and at the boot prompt,
        enter the <option>-s</option> flag.  The system will then boot
	single user.  At the shell prompt you should then run:</para>

      <screen>&prompt.root; <userinput>fsck -p</userinput>
&prompt.root; <userinput>mount -u /</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput>
&prompt.root; <userinput>swapon -a</userinput></screen>

      <para>This checks the filesystems, remounts <filename>/</filename>
	read/write, mounts all the other UFS filesystems referenced in
	<filename>/etc/fstab</filename> and then turns swapping on.</para>
    </sect2>

    <sect2>
      <title>Remove <filename>/usr/obj</filename></title>

      <para>As parts of the system are rebuilt they are placed in
	directories which (by default) go under
	<filename>/usr/obj</filename>.  The directories shadow those under
	<filename>/usr/src</filename>.</para>

      <para>You can speed up the <quote>make world</quote> process, and
	possibly  save yourself some dependency headaches by removing this
	directory as well.</para>

      <para>Some files below <filename>/usr/obj</filename> will have the
	immutable flag set (see &man.chflags.1; for more information)
	which must be removed first.</para>

      <screen>&prompt.root; <userinput>cd /usr/obj</userinput>
&prompt.root; <userinput>chflags -R noschg *</userinput>
&prompt.root; <userinput>rm -rf *</userinput></screen>
    </sect2>

    <sect2>
      <title/Recompile the source and install the new system/

      <sect3>
	<title>All versions</title>

	<para>You must be in the <filename>/usr/src</filename>
	  directory...</para>

	<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>

	<para>(unless, of course, your source code is elsewhere, in which
	  case change to that directory instead).</para>

	<para>To rebuild the world you use the &man.make.1; command.  This
	  command reads instructions from the
	  <filename>Makefile</filename> which describes how the programs
	  that comprise FreeBSD should be rebuilt, the order they should
	  be built in, and so on.</para>

	<para>The general format of the command line you will type is as
	  follows:</para>

	<screen>&prompt.root; <userinput>make <option>-<replaceable/x/</option> <option>-D<replaceable>VARIABLE</replaceable></option> <replaceable>target</replaceable></userinput></screen>

	<para>In this example, <option>-<replaceable>x</replaceable></option>
	  is an option that you would pass to &man.make.1;.  See the
	  &man.make.1; manual page for an example of the options you can
	  pass.</para>

	<para><option>-D<replaceable>VARIABLE</replaceable></option>
	  passes a variable to the <filename>Makefile</filename>.  The
	  behavior of the <filename>Makefile</filename> is controlled by
	  these variables.  These are the same variables as are set in
	  <filename>/etc/make.conf</filename>, and this provides another
	  way of setting them.</para>

	<screen>&prompt.root; <userinput>make -DNOPROFILE=true <replaceable>target</replaceable></userinput></screen>

	<para>is another way of specifying that profiled libraries should
	  not be built, and corresponds with the</para>

	<programlisting>NOPROFILE=    true
#    Avoid compiling profiled libraries</programlisting>

	<para>lines in <filename>/etc/make.conf</filename>.</para>

	<para><replaceable>target</replaceable> tells &man.make.1; what
	  you want to do.  Each <filename>Makefile</filename> defines a
	  number of different <quote>targets</quote>, and your choice of
	  target determines what happens.</para>

	<para>Some targets are listed in the
	  <filename>Makefile</filename>, but are not meant for you to run.
	  Instead, they are used by the build process to break out the
	  steps necessary to rebuild the system into a number of
	  sub-steps.</para>

	<para>Most of the time you won't need to pass any parameters to
	    &man.make.1;, and so your command like will look like
	    this:</para>

	<screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen>
      </sect3>

      <sect3>
	<title>Saving the output</title>

	<para>It's a good idea to save the output you get from running
	  &man.make.1; to another file.  If something goes wrong you will
	  have a copy of the error message, and a complete list of where
	  the process had got to.  While this might not help you in
	  diagnosing what has gone wrong, it can help others if you post
	  your problem to one of the FreeBSD mailing lists.</para>

	<para>The easiest way to do this is to use the &man.script.1;
	  command, with a parameter that specifies the name of the file to
	  save all output to.  You would do this immediately before
	  remaking the world, and then type <userinput>exit</userinput>
	  when the process has finished.</para>

	<screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
Script started, output file is /var/tmp/mw.out	 
&prompt.root; <userinput>make world</userinput>
<emphasis>&hellip; compile, compile, compile &hellip;</emphasis>	  
&prompt.root; <userinput>exit</userinput>
Script done, &hellip;</screen>

	<para>If you do this, <emphasis>do not</emphasis> save the output
	  in <filename>/tmp</filename>.  This directory may be cleared
	  next time you reboot.  A better place to store it is in
	  <filename>/var/tmp</filename> (as in the previous example) or
	  in <username>root</username>'s home directory.</para>
      </sect3>

      <sect3>
	<title>Version 2.2.2 and below</title>

	<para><filename>/usr/src/Makefile</filename> contains the
	  <maketarget>world</maketarget> target, which will rebuild the
	  entire system and then install it.</para>

	<para>Use it like this:</para>

	<screen>&prompt.root; <userinput>make world</userinput></screen>
      </sect3>
      
      <sect3>
	<title>Version 2.2.5 and above</title>

	<para>Beginning with version 2.2.5 of FreeBSD (actually, it was
	  first created on the -CURRENT branch, and then retrofitted to
	  -STABLE midway between 2.2.2 and 2.2.5) the
	  <maketarget>world</maketarget> target has been split in
	  two.  <maketarget>buildworld</maketarget> and
	  <maketarget>installworld</maketarget>.</para>

	<para>As the names imply, <maketarget>buildworld</maketarget>
	  builds a complete new tree under <filename>/usr/obj</filename>,
	  and <maketarget>installworld</maketarget> installs this tree on
	  the current machine.</para>

	<para>This is very useful for 2 reasons.  First, it allows you to do
	  the build safe in the knowledge that no components of your running
	  system will be affected.  The build is <quote>self hosted</quote>.
	  Because of this, you can safely run
	  <maketarget>buildworld</maketarget> on a machine running in
	  multi-user mode with  no fear of ill-effects.  I still recommend you
	  run the <maketarget>installworld</maketarget> part in single user
	  mode though.</para>

	<para>Secondly, it allows you to use NFS mounts to upgrade 
	  multiple machines on your network.  If you have three machines,
	  A, B and C that you want to upgrade, run <command>make
	  buildworld</command> and <command>make installworld</command> on
	  A.  B and C should then NFS mount <filename>/usr/src</filename>
	  and <filename>/usr/obj</filename> from A, and you can then run
	  <command>make installworld</command> to install the results of 
	  the build on B and C.</para>

	<para>The <maketarget>world</maketarget> target still exists, and
	  you can use it exactly as shown for version 2.2.2.
	  <command>make world</command> runs <command>make 
	  buildworld</command> followed by <command>make
	  installworld</command>.</para>

	<note>
	  <para>If you do the <command>make buildworld</command> and 
	    <command>make installworld</command> commands separately, you
	    must pass the same parameters to &man.make.1; each
	    time.</para>

	  <para>If you run:</para>

	  <screen>&prompt.root; <userinput>make -DNOPROFILE=true buildworld</userinput></screen>

	  <para>you must install the results with:</para>

	  <screen>&prompt.root; <userinput>make -DNOPROFILE=true installworld</userinput></screen>

	  <para>otherwise it would try and install profiled libraries that
	    had not been built during the <command>make buildworld</command>
	    phase.</para>
	</note>
      </sect3>
      
      <sect3>
	<title>-CURRENT and above</title>

	<para>If you are tracking -CURRENT you can also pass the
	  <option>-j</option> option to <command>make</command>.  This lets
	  <command>make</command> spawn several simultaneous processes.</para>

	<para>This is most useful on true multi-CPU machines.  However, since
	  much of the compiling process is IO bound rather than CPU bound it is
	  also useful on single CPU machines.</para>

	<para>On a typical single-CPU machine you would run:</para>
	  
	  <screen>&prompt.root; <userinput>make -j4 <replaceable>target</replaceable></userinput></screen>

	<para>&man.make.1; will then have up to 4 processes running at any one
	  time. Empirical evidence posted to the mailing lists shows this
	  generally gives the best performance benefit.</para>

	<para>If you have a multi-CPU machine and you are using an SMP
	  configured kernel try values between 6 and 10 and see how they speed
	  things up.</para>

	<para>Be aware that (at the time of writing) this is still
	  experimental, and commits to the source tree may occasionally break
	  this feature. If  the world fails to compile using this parameter
	  try again without it before you report any problems.</para>
      </sect3>
      
      <sect3>
	<title>Timings</title>

	<para>Assuming everything goes well you have anywhere between an hour
	  and a half and a day or so to wait.</para>

	<para>As a general rule of thumb, a 200MHz P6 with more than 32MB of
	  RAM  and reasonable SCSI disks will complete <command>make
	    world</command> in about an hour and a half.  A 32MB P133 will
	  take 5 or 6 hours.  Revise these figures down if your machines are
	  slower&hellip;</para>
      </sect3>
    </sect2>
    
    <sect2>
      <title>Update <filename>/etc</filename></title>
      
      <para>Remaking the world will not update certain directories (in
	particular, <filename>/etc</filename>, <filename>/var</filename> and
	<filename>/usr</filename>) with new or changed configuration files.
	This is something you have to do by hand, eyeball, and judicious use
	of &man.diff.1;.</para>
    
      <para>You cannot just copy over the files from
	<filename>/usr/src/etc</filename> to <filename>/etc</filename> and
	have it work.  Some of these files must be <quote>installed</quote>
	first.  This is because the <filename>/usr/src/etc</filename>
	directory <emphasis>is not</emphasis> a copy of what your
	<filename>/etc</filename> directory should look like.  In addition,
	there  are files that should be in <filename>/etc</filename> that are
	not in <filename>/usr/src/etc</filename>.</para>
    
      <para>The simplest way to do this is to install the files into a new
	directory, and then work through them looking for differences.</para>
    
      <warning>
	<title>Backup your existing <filename>/etc</filename></title>

	<para>Although, in theory, nothing is going to touch this directory
	  automatically, it is always better to be sure.  So copy your
	  existing <filename>/etc</filename> directory somewhere safe.
	  Something like:</para>

	<screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>

	<para><option>-R</option> does a recursive copy, <option>-p</option>
	  preserves times, ownerships on files and suchlike.</para>
      </warning>
      
      <para>You need to build a dummy set of directories to install the new
	<filename>/etc</filename> and other files into.  I generally choose to
	put this dummy directory in <filename>/var/tmp/root</filename>, and
	there are a number of subdirectories required under this as
	well.</para>

      <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput>
&prompt.root; <userinput>cd /usr/src/etc</userinput>
&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen>

      <para>This will build the necessary directory structure and install the
	files.  A lot of the subdirectories that have been created under
	<filename>/var/tmp/root</filename> are empty and should be deleted.
	The simplest way to do this is to:</para>
      
      <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput>
&prompt.root; <userinput>find -d .  -type d | /usr/bin/perl -lne \
    'opendir(D,$_);@f=readdir(D);rmdir if $#f == 1;closedir(D);'</userinput></screen>
      
      <para>This does a depth first search, examines each directory, and if
	the number of files in that directory is 2 (<quote/1/ is not a typo in
	the script) i.e., <quote/<filename/.// and <quote/<filename/..// then
	it removes the directory.</para>
    
      <para><filename>/var/tmp/root</filename> now contains all the files that
	should be placed in appropriate locations below
	<filename>/</filename>.  You now have to go through each of these
	files, determining how they differ with your existing files.</para>
    
      <para>Note that some of the files that will have been installed in
	<filename>/var/tmp/root</filename> have a leading <quote/./.  At the
	time of writing the only files like this are shell startup files in
	<filename>/var/tmp/root/</filename> and
	<filename>/var/tmp/root/root/</filename>, although there may be others
	(depending on when you are reading this.  Make sure you use
	<command/ls -a/ to catch them.</para>
    
      <para>The simplest way to do this is to use &man.diff.1; to compare the
	two files.</para>
    
      <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen>
      
      <para>This will show you the differences between your
	<filename>/etc/shells</filename> file and the new
	<filename>/etc/shells</filename> file.  Use these to decide whether to
	merge in changes that you have made or whether to copy over your old
	file.</para>
    
      <tip>
	<title>Name the new root directory
	  (<filename>/var/tmp/root</filename>)with a time stamp, so you can
	  easily compare differences between versions</title>

	<para>Frequently remaking the world means that you have to update
	<filename>/etc</filename> frequently as well, which can be a bit of
	  a chore.</para>

	<para>You can speed this process up by keeping a copy of the last set
	  of changed files that you merged into <filename>/etc</filename>.
	  The  following procedure gives one idea of how to do this.</para>

	<procedure>
	  <step>
	    <para>Make the world as normal.  When you want to update
	      <filename>/etc</filename> and the other directories, give the
	      target directory a name based on the current date.  If you were
	      doing this on the 14th of February 1998 you could do the
	      following.</para>
	  
	    <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput>
&prompt.root; <userinput>cd /usr/src/etc</userinput>
&prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \
    distrib-dirs distribution</userinput></screen>
	  </step>
	  
	  <step>
	    <para>Merge in the changes from this directory as outlined
	      above.</para>
	    
	    <para><emphasis>Do not</emphasis> remove the
	      <filename>/var/tmp/root-19980214</filename> directory when you
	      have finished.</para>
	  </step>
	  
	  <step>
	    <para>When you have downloaded the latest version of the source
	      and remade it, follow step 1.  This will give you a new
	      directory, which might be called
	      <filename>/var/tmp/root-19980221</filename> (if you wait a week
	      between doing updates).</para>
	  </step>
	  
	  <step>
	    <para>You can now see the differences that have been made in the
	      intervening week using &man.diff.1; to create a recursive diff
	      between the two directories.</para>
	      
	    <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
&prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen>
	  
	    <para>Typically, this will be a much smaller set of differences
	      than those between
	      <filename>/var/tmp/root-19980221/etc</filename> and
	      <filename>/etc</filename>.  Because the set of differences is
	      smaller, it is easier to migrate those changes across into your
	      <filename>/etc</filename> directory.</para>
	  </step>
	  
	  <step>
	    <para>You can now remove the older of the two
	      <filename>/var/tmp/root-*</filename> directories.</para>
	      
	    <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen>
	  </step>
	  
	  <step>
	    <para>Repeat this process every time you need to merge in changes
	      to  <filename>/etc</filename>.</para>
	  </step>
	</procedure>

	<para>You can use &man.date.1; to automate the  generation of the
	  directory names.</para>
	  
	<screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
      </tip>
    </sect2>
  
    <sect2>
      <title>Update <filename>/dev</filename></title>
      
      <note>
	<title>DEVFS</title>

	<para>If you are using DEVFS then this is probably unnecessary.</para>
      </note>
      
      <para>For safety's sake, this is a multi-step process.</para>

      <procedure>
	<step>
	  <para>Copy <filename>/var/tmp/root/dev/MAKEDEV</filename> to
	    <filename>/dev</filename>.</para>

	  <screen>&prompt.root; <userinput>cp /var/tmp/root/dev/MAKEDEV /dev</userinput></screen>
	</step>

	<step>
	  <para>Now, take a snapshot of your current
	    <filename>/dev</filename>.  This  snapshot needs to contain the
	    permissions, ownerships, major and minor numbers of each filename,
	    but it should not contain the time stamps.  The easiest way to do
	    this is to use &man.awk.1; to strip out some of the
	    information.</para>

	  <screen>&prompt.root; <userinput>cd /dev</userinput>
&prompt.root; <userinput>ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.out</userinput></screen>
	</step>

	<step>
	  <para>Remake all the devices.</para>
	    
	    <screen>&prompt.root; <userinput/sh MAKEDEV all/</screen>
	</step>

	<step>
	  <para>Write another snapshot of the directory, this time to
	    <filename>/var/tmp/dev2.out</filename>.  Now look through these
	    two files for any devices that you missed creating.  There should
	    not be any, but it is better to be safe than sorry.</para>

	  <screen>&prompt.root; <userinput>diff /var/tmp/dev.out /var/tmp/dev2.out</userinput></screen>

	  <para>You are most likely to notice disk slice discrepancies which
	    will involve commands such as
	  
	    <screen>&prompt.root; <userinput>sh MAKEDEV sd0s1</userinput></screen>

	    to recreate the slice entries.  Your precise circumstances may
	    vary.</para>
	</step>
      </procedure>
    </sect2>
    
    <sect2>
      <title>Update <filename>/stand</filename></title>
      
      <note>
	<para>This step is included only for completeness.  It can safely be
	  omitted.</para>
      </note>
      
      <para>For the sake of completeness, you may want to update the files in
	<filename>/stand</filename> as well.  These files consist of hard
	links to the <filename>/stand/sysinstall</filename> binary.  This
	binary should  be statically linked, so that it can work when no other
	filesystems (and  in particular <filename>/usr</filename>) have been
	mounted.</para>

      <screen>&prompt.root; <userinput>cd /usr/src/release/sysinstall</userinput>
&prompt.root; <userinput>make all install</userinput></screen>

      <note>
	<title>Source older than 2 April 1998</title>

	<para>If your source code is older than 2nd April 1998, or the
	  <filename>Makefile</filename> version is not 1.68 or higher (for
	  FreeBSD current and 3.X systems) or 1.48.2.21 or higher (for 2.2.X
	  systems) you will need to add the
	  <userinput>NOSHARED=yes</userinput> option, like so;</para>

	<screen>&prompt.root; <userinput>make NOSHARED=yes all install</userinput></screen>
      </note>
    </sect2>
    
    <sect2>
      <title>Compile and install a new kernel</title>

      <para>To take full advantage of your new system you should recompile the
	kernel.  This is practically a necessity, as certain memory structures
	may have changed, and programs like &man.ps.1; and &man.top.1; will
	fail to work until the kernel and source code versions are the
	same.</para>

      <para>Follow the handbook instructions for compiling a new kernel.  If
	you have previously built a custom kernel then carefully examine the
	<filename>LINT</filename> config file to see if there are any new
	options which you should take advantage of.</para>

      <para>A previous version of this document suggested rebooting before
	rebuilding the kernel.  This is wrong because:</para>

      <itemizedlist>
	<listitem>
	  <para>Commands like &man.ps.1;, &man.ifconfig.8;, and &man.sysctl.8; 
	    may fail.  This could leave your machine unable to connect to the
	    network.</para>
	</listitem>
      
	<listitem>
	  <para>Basic utilities like &man.mount.8; could fail,
	    making it impossible to mount <filename>/</filename>,
	    <filename>/usr</filename> and so on.  This is unlikely if you are
	    tracking a -STABLE candidate, but more likely if you are tracking
	    -CURRENT during a large merge.</para>
	</listitem>

	<listitem>
	  <para>Loadable kernel modules (LKMs on pre-3.X systems, KLDs on 3.X
	    systems and above) built as part of the <quote>world</quote> may
	    crash an older kernel.</para>
	</listitem>
      </itemizedlist>

      <para>For these reasons, it is always best to rebuild and install a
	new kernel before rebooting.</para>

      <para>You should build your new kernel after you have completed
	<userinput>make world</userinput> (or <userinput>make
	  installworld</userinput>).  If you do not want to do this (perhaps
	you want to confirm that the kernel builds before updating your
	system) you may have problems.  These may be because your
	  &man.config.8; command is out of date with respect to your kernel
	sources.</para>

      <para>In this case you could build your kernel with the new version of &man.config.8;</para>
      
      <screen>&prompt.root; <userinput>/usr/obj/usr/src/usr.sbin/config/config <replaceable>KERNELNAME</replaceable></userinput></screen>

      <para>This may not work in all cases.  It is recommended that you
	complete <userinput>make world</userinput> (or <userinput>make
	  installworld</userinput>) before compiling a new kernel.</para>
    </sect2>
    
    <sect2>
      <title/Rebooting/
      
      <para>You are now done.  After you have verified that everything appears
	to be in the right place you can reboot the system.  A simple
	&man.fastboot.8; should do it.</para>

      <screen>&prompt.root; <userinput>fastboot</userinput></screen>
    </sect2>

    <sect2>
      <title>Finished</title>
      
      <para>You should now have successfully upgraded your FreeBSD system.
	Congratulations.</para>
      
      <para>You may notice small problems due to things that you have missed.
	For example, I once deleted <filename>/etc/magic</filename> as part of
	the upgrade and merge to <filename>/etc</filename>, and the
	<command>file</command> command stopped working.  A moment's thought
	meant that

	<screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
&prompt.root; <userinput/make all install/</screen>

	was sufficient to fix that one.</para>
    </sect2>    
    
    <sect2>
      <title/Questions?/

      <qandaset>
	<qandaentry>
	  <question>
	    <para>Do I need to re-make the world for every change?</para>
	  </question>

	  <answer>
            <para>There is no easy answer to this one, as it depends on the
	      nature of the change.  For example, I have just run CVSup, and
	      it has shown the following files as being updated since I last
	      ran it;</para>
      
	    <screen><filename>src/games/cribbage/instr.c</filename>
<filename>src/games/sail/pl_main.c</filename>
<filename>src/release/sysinstall/config.c</filename>
<filename>src/release/sysinstall/media.c</filename>
<filename>src/share/mk/bsd.port.mk</filename></screen>

	    <para>There is nothing in there that I would re-make the world
	      for.  I would go to the appropriate sub-directories and
	      <command>make all install</command>, and that's about it.  But
	      if something major changed, for example
	      <filename>src/lib/libc/stdlib</filename> then I would either
	      re-make the world, or at least those parts of it that are
	      statically linked (as well as anything else I might have added
	      that is statically linked).</para>
      
	    <para>At the end of the day, it is your call.  You might be happy
	      re-making the world every fortnight say, and let changes
	      accumulate over that fortnight.  Or you might want to re-make
	      just those things that have changed, and are confident you can
	      spot all the dependencies.</para>
      
	    <para>And, of course, this all depends on how often you want to
	      upgrade, and whether you are tracking -STABLE or
	      -CURRENT.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>My compile failed with lots of signal 12 (or other signal
	      number) errors.  What has happened?</para>
	  </question>

	  <answer>
	    <para>This is normally indicative of hardware problems.
	      (Re)making the world is an effective way to stress test your
	      hardware, and will frequently throw up memory problems.  These
	      normally manifest themselves as the compiler mysteriously dying
	      on receipt of strange signals.</para>
      
	    <para>A sure indicator of this is if you can restart the make and
	      it dies at a different point in the process.</para>
      
	    <para>In this instance there is little you can do except start
	      swapping around the components in your machine to determine
	      which one is failing.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>Can I remove <filename>/usr/obj</filename> when I have
	      finished?</para>
	  </question>
	  
	  <answer>
	    <para>That depends on how you want to make the world on future
	      occasions.</para>
      
	    <para><filename>/usr/obj</filename> contains all the object files
	      that were produced during the compilation phase.  Normally, one
	      of the first steps in the <quote/make world/ process is to
	      remove this directory and start afresh.  In this case, keeping
	      <filename>/usr/obj</filename> around after you have finished
	      makes little sense, and will free up a large chunk of disk space
	      (currently about 150MB).</para>
      
	    <para>However, if you know what you are doing you can have
	      <quote/make world/ skip this step.  This will make subsequent
	      builds run much faster, since most of sources will not need to
	      be recompiled.  The flip side of this is that subtle dependency
	      problems can creep in, causing your build to fail in odd ways.
	      This frequently generates noise on the FreeBSD mailing lists,
	      when one person complains that their build has failed, not
	      realising that it is because they have tried to cut
	      corners.</para>
      
	    <para>If you want to live dangerously then make the world, passing
	      the <makevar>NOCLEAN</makevar> definition to make, like
	      this:</para>

	    <screen>&prompt.root; <userinput>make -DNOCLEAN world</userinput></screen>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>Can interrupted builds be resumed?</para>
	  </question>

	  <answer>
	    <para>This depends on how far through the process you got before
	      you found a problem.</para>

	    <para><emphasis>In general</emphasis> (and this is not a hard and
	      fast rule) the <quote>make world</quote> process builds new
	      copies of essential tools (such as &man.gcc.1;, and
	      &man.make.1;>) and the system libraries.  These tools and
	      libraries are then installed.  The new tools and libraries are
	      then used to rebuild themselves, and are installed again. The
	      entire system (now including regular user programs, such as
		&man.ls.1; or &man.grep.1;) is then rebuilt with the new
	      system files.</para>

	    <para>If you are at the last state, and you know it (because you
	      have looked through the output that you were storing) then you
	      can (fairly safely) do</para>

	    <screen><emphasis>&hellip; fix the problem &hellip;</emphasis>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make -DNOCLEAN all</userinput></screen>

	    <para>This will not undo the work of the previous
	      <quote>make world</quote>.</para>

	    <para>If you see the message

	      <screen>--------------------------------------------------------------
Building everything..
--------------------------------------------------------------</screen>

	      in the <quote>make world</quote> output then it is
	      probably fairly safe to do so.</para>
	    
	    <para>If you do not see that message, or you are not sure, then it
	      is always better to be safe than sorry, and restart the build
	      from scratch.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>Can I use one machine as a <emphasis/master/ to upgrade lots
	      of machines (NFS)?</para>
	  </question>

	  <answer>
	    <para>People often ask on the FreeBSD mailing lists whether they
	      can do all the compiling on one machine, and then use the
	      results of that compile to <command>make install</command> on to
	      other machines around the network.</para>
      
	    <para>This is not something I have done, so the suggestions below
	      are either from other people, or deduced from the
	      Makefiles.</para>
	    
	    <para>The precise approach to take depends on your version of
	      FreeBSD</para>
	    
	    <para>You must still upgrade <filename>/etc</filename> and
	      <filename>/dev</filename> on the target machines after doing
	      this.</para>
	    
	    <para>For 2.1.7 and below, Antonio Bemfica
	      suggested the following approach:</para>

	    <screen>Date: Thu, 20 Feb 1997 14:05:01 -0400 (AST)
From: Antonio Bemfica &lt;bemfica@militzer.me.tuns.ca&gt;
To: freebsd-questions@FreeBSD.org
Message-ID: &lt;Pine.BSI.3.94.970220135725.245C-100000@militzer.me.tuns.ca&gt;

Josef Karthauser asked:

&gt; Has anybody got a good method for upgrading machines on a network

First make world, etc.  on your main machine
Second, mount / and /usr from the remote machine:

main_machine% mount remote_machine:/   /mnt
main_machine% mount remote_machine:/usr /mnt/usr

Third, do a 'make install' with /mnt as the destination:

main_machine% make install DESTDIR=/mnt

Repeat for every other remote machine on your network.   It works fine
for me.
     
Antonio</screen>

	    <para>This mechanism will only work (to the best of my knowledge)
	      if you can write to <filename>/usr/src</filename> on the NFS
	      server, as  the <maketarget>install</maketarget> target in 2.1.7
	      and below needed to do this.</para>
	    
	    <para>Midway between 2.1.7 and 2.2.0 the <quote>reinstall</quote>
	      target was committed.  You can use the approach exactly as
	      outlined above for 2.1.7, but use <quote>reinstall</quote>
	      instead of <quote>install</quote>.</para>

	    <para>This approach <emphasis>does not</emphasis> require write
	      access to the <filename>/usr/src</filename> directory on the NFS
	      server.</para>

	    <para>There was a bug introduced in this target between versions
	      1.68 and 1.107 of the Makefile, which meant that write access to
	      the NFS server <emphasis>was</emphasis> required.  This bug was
	      fixed before version 2.2.0 of FreeBSD was released, but may be an
	      issue of you have an old server still running -STABLE from this
	      era.</para>

	    <para>For version 2.2.5 and above, you can use the
	      <quote>buildworld</quote> and <quote>installworld</quote>
	      targets.  Use them to build a source tree on one machine, and
	      then NFS mount <filename>/usr/src</filename> and
	      <filename>/usr/obj</filename> on the remote machine and install
	      it there.</para>
	  </answer>
	</qandaentry>

	<qandaentry>
	  <question>
	    <para>How can I speed up making the world?</para>

	    <itemizedlist>
	      <listitem>
		<para>Run in single user mode.</para>
	      </listitem>
	      
	      <listitem>
		<para>Put the <filename>/usr/src</filename> and
		  <filename>/usr/obj</filename> directories on separate
		  filesystems held on separate disks.  If possible, put these
		  disks on separate disk controllers.</para>
	      </listitem>
	      
	      <listitem>
		<para>Better still, put these filesystems across separate
		  disks using the <quote>ccd</quote> (concatenated disk
		  driver) device.</para>
	      </listitem>
	      
	      <listitem>
		<para>Turn off profiling (set <quote>NOPROFILE=true</quote> in
		  <filename>/etc/make.conf</filename>).  You almost certainly
		  do not need it.</para>
	      </listitem>
	      
	      <listitem>
		<para>Also in <filename>/etc/make.conf</filename>, set
		  <quote>CFLAGS</quote> to something like <quote>-O
		    -pipe</quote>. The optimization <quote>-O2</quote> is much
		  slower, and the optimization difference between
		  <quote>-O</quote> and <quote>-O2</quote> is normally
		  negligible.  <quote>-pipe</quote> lets the compiler use
		  pipes rather than temporary files for communication, which
		  saves disk access (at the expense of memory).</para>
	      </listitem>
	      
	      <listitem>
		<para>Pass the <option>-j&lt;n&gt;</option> option to make (if
		  you are running a sufficiently recent version of FreeBSD) to
		  run multiple processes in parallel.  This helps regardless
		  of whether you have a single or a multi processor
		  machine.</para>
	      </listitem>
	      
	      <listitem><para>The filesystem holding
		  <filename>/usr/src</filename> can be mounted (or remounted)
		  with the <quote>noatime</quote> option.  This stops the time
		  files in the filesystem were last accessed from being
		  written to the disk.  You probably do not need this
		  information anyway.

		  <note>
		    <para><quote>noatime</quote> is in version 2.2.0 and
		      above.</para>
		  </note>
		  
		  <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>
		  
		  <warning>
		    <para>The example assumes <filename>/usr/src</filename> is
		      on its own filesystem.  If it is not (if it is a part of
		      <filename>/usr</filename> for example) then you will
		      need to use  that filesystem mount point, and not
		      <filename>/usr/src</filename>.</para>
		  </warning>
		</para>
	      </listitem>
	      
	      <listitem>
		<para>The filesystem holding <filename>/usr/obj</filename> can
		  be mounted (or remounted) with the <quote>async</quote>
		  option.  This causes disk writes to happen asynchronously.
		  In other words, the write completes immediately, and the
		  data is written to the disk a few seconds later.  This
		  allows writes to be clustered together, and can be a
		  dramatic performance boost.</para>

		<warning>
		  <para>Keep in mind that this option makes your filesystem
		    more fragile.  With this option there is an increased
		    chance that, should power fail, the filesystem will be in
		    an unrecoverable state when the machine restarts.</para>
	   
		  <para>If <filename>/usr/obj</filename> is the only thing on
		    this filesystem then it is not a problem.  If you have
		    other, valuable data on the same filesystem then ensure
		    your backups are fresh before you enable this
		    option.</para>
		</warning>
		
		<screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>
		
		<warning>
		  <para>As above, if <filename>/usr/obj</filename> is not on
		    its own filesystem, replace it in the example with the
		    name of the appropriate mount point.</para>
		</warning>
	      </listitem>
	    </itemizedlist>
	  </question>
	</qandaentry>
      </qandaset>
    </sect2>
  </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: ("../book.sgml" "part" "chapter")
     End:
-->