Rewrite the Build from Source section, simplifying and clarifying.

Differential Revision:	https://reviews.freebsd.org/D7665

1 files changed, 371 insertions, 970 deletions

diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
index 36714d021b..137d09e99c 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
@@ -1067,1044 +1067,445 @@ before running "/usr/sbin/freebsd-update install"</screen>
 	</listitem>
       </orderedlist>
     </sect2>
-
-    <sect2 xml:id="stable">
-      <title>Using &os.stable;</title>
-
-      <para>&os.stable; is the development branch from which major
-	releases are made.  Changes go into this branch at a slower
-	pace and with the general assumption that they have first been
-	tested in &os.current;.  This is <emphasis>still</emphasis> a
-	development branch and, at any given time, the sources for
-	&os.stable; may or may not be suitable for general use.  It is
-	simply another engineering development track, not a resource
-	for end-users.  Users who do not have the resources to perform
-	testing should instead run the most recent release of
-	&os;.</para>
-
-      <para>Those interested in tracking or contributing to the &os;
-	development process, especially as it relates to the next
-	release of &os;, should consider following &os.stable;.</para>
-
-      <para>While the &os.stable; branch should compile and run at all
-	times, this cannot be guaranteed.  Since more people run
-	&os.stable; than &os.current;, it is inevitable that bugs and
-	corner cases will sometimes be found in &os.stable; that were
-	not apparent in &os.current;.  For this reason, one should not
-	blindly track &os.stable;.  It is particularly important
-	<emphasis>not</emphasis> to update any production servers to
-	&os.stable; without thoroughly testing the code in a
-	development or testing environment.</para>
-
-      <para>To track &os.stable;:</para>
-
-      <indexterm>
-	<primary>-STABLE</primary>
-	  <secondary>using</secondary>
-      </indexterm>
-      <orderedlist>
-	<listitem>
-	  <para>Join the &a.stable.name; list in order to stay
-	    informed of build dependencies that may appear in
-	    &os.stable; 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>Join the relevant <application>svn</application> list
-	    for the branch being tracked.  For example, users
-	    tracking the 9-STABLE branch should join the
-	    &a.svn-src-stable-9.name; list.  This list records 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, go to &a.mailman.lists.link;,
-	    click on the list to subscribe to, and follow the
-	    instructions.  In order to track changes for the whole
-	    source tree, subscribe to &a.svn-src-all.name;.</para>
-	</listitem>
-
-	<listitem>
-	  <para>To install a new &os.stable; system, install the most
-	    recent &os.stable; release from the <link
-	      linkend="mirrors">&os; mirror sites</link> or use a
-	    monthly snapshot built from &os.stable;.  Refer to <link
-	      xlink:href="&url.base;/snapshots/">www.freebsd.org/snapshots</link>
-	    for more information about snapshots.</para>
-
-	  <para>To compile or upgrade to an existing &os; system to
-	    &os.stable;, use <link linkend="svn">svn</link>
-	      <indexterm>
-		<primary>Subversion</primary>
-	      </indexterm> to check out the source for the desired
-	    branch.  Branch names, such as
-	    <literal>stable/9</literal>, are listed at <link
-	      xlink:href="&url.base;/releng/">www.freebsd.org/releng</link>.</para>
-	</listitem>
-
-	<listitem>
-	  <para>Before compiling or upgrading to &os.stable;
-	    <indexterm>
-	      <primary>-STABLE</primary>
-		<secondary>compiling</secondary>
-	    </indexterm>, read <filename>/usr/src/Makefile</filename>
-	    carefully and follow the instructions in <xref
-	      linkend="makeworld"/>.  Read &a.stable; and
-	    <filename>/usr/src/UPDATING</filename> to keep up-to-date
-	    on other bootstrapping procedures that sometimes become
-	    necessary on the road to the next release.</para>
-	</listitem>
-      </orderedlist>
-    </sect2>
   </sect1>
 
-  <sect1 xml:id="synching">
-    <title>Synchronizing Source</title>
+  <sect1 xml:id="updating-src">
+    <title>Updating &os; from Source</title>
 
-    <para>There are various methods for staying up-to-date with the
-      &os; sources.  This section describes the primary service,
-      <application>Subversion</application>.</para>
+    <para>Updating &os; by compiling from source offers several
+      advantages over binary updates.  Code can be built with options
+      to take advantage of specific hardware.  Parts of the base
+      system can be built with non-default settings, or left out
+      entirely where they are not needed or desired.  The build
+      process takes longer to update a system than binary updates, but
+      allows complete customization to produce a tailored version of
+      &os;.</para>
 
-    <warning>
-      <para>While it is possible to update only parts of the source
-	tree, the only supported update procedure is to update the
-	entire tree and recompile all the programs that run in user
-	space, such as those in <filename>/bin</filename> and
-	<filename>/sbin</filename>, and kernel sources.  Updating only
-	part of the source tree, only the kernel, or only the userland
-	programs will often result in problems ranging from compile
-	errors to kernel panics or data corruption.</para>
-    </warning>
+    <sect2 xml:id="updating-src-quick-start">
+      <title>Quick Start</title>
 
-    <indexterm>
-      <primary>Subversion</primary>
-    </indexterm>
-
-    <para><application>Subversion</application> uses the
-      <emphasis>pull</emphasis> model of updating sources.  The user,
-      or a <command>cron</command> script, invokes the
-      <command>svn</command> program which updates the local version
-      of the source.  <application>Subversion</application> is the
-      preferred method for updating local source trees as updates are
-      up-to-the-minute and the user controls when updates are
-      downloaded.  It is easy to restrict updates to specific files or
-      directories and the requested updates are generated on the fly
-      by the server.  How to synchronize source using
-      <application>Subversion</application> is described in <xref
-	linkend="svn"/>.</para>
-
-    <para>If a user inadvertently wipes out portions of the local
-      archive, <application>Subversion</application> will detect and
-      rebuild the damaged portions during an update.</para>
-  </sect1>
-
-  <sect1 xml:id="makeworld">
-    <title>Rebuilding World</title>
-
-    <indexterm>
-      <primary>Rebuilding <quote>world</quote></primary>
-    </indexterm>
-    <para>Once the local source tree is synchronized against a
-      particular version of &os; such as &os.stable; or &os.current;,
-      the source tree can be used to rebuild the system.  This process
-      is known as rebuilding world.</para>
-
-    <para><emphasis>Before</emphasis> rebuilding world, be sure to
-      perform the following tasks:</para>
-
-    <procedure>
-      <title>Perform These Tasks <emphasis>Before</emphasis>
-	Building World</title>
-
-      <step>
-	<para>Backup all important data to another system or removable
-	  media, verify the integrity of the backup, and have a
-	  bootable installation media at hand.  It cannot be stressed
-	  enough how important it is to make a backup of the system
-	  <emphasis>before</emphasis> rebuilding the system.  While
-	  rebuilding world is an easy task, there will inevitably be
-	  times when mistakes in the source tree render the system
-	  unbootable.  You will probably never have to use the backup,
-	  but it is better to be safe than sorry!</para>
-      </step>
-
-      <step>
-	<indexterm><primary>mailing list</primary></indexterm>
-	<para>Review the recent &a.stable.name; or &a.current.name;
-	  entries, depending upon the branch being tracked.  Be aware
-	  of any known problems and which systems are affected.  If a
-	  known issue affects the version of synchronized code, wait
-	  for an <quote>all clear</quote> announcement to be posted
-	  stating that the problem has been solved.  Resynchronize the
-	  sources to ensure that the local version of source has the
-	  needed fix.</para>
-      </step>
-
-      <step>
-	<para>Read <filename>/usr/src/UPDATING</filename> for any
-	  extra steps necessary for that version of the source.  This
-	  file contains important information about potential problems
-	  and may specify the order to run certain commands.  Many
-	  upgrades require specific additional steps such as renaming
-	  or deleting specific files prior to installing the new
-	  world.  These will be listed at the end of this file where
-	  the currently recommended upgrade sequence is explicitly
-	  spelled out.  If <filename>UPDATING</filename> contradicts
-	  any steps in this chapter, the instructions in
-	  <filename>UPDATING</filename> take precedence and should be
-	  followed.</para>
-      </step>
-    </procedure>
-
-    <warning>
-      <title>Do Not Use <command>make world</command></title>
-
-      <para>Some older documentation recommends using <command>make
-	  world</command>.  However, that command skips some important
-	steps and should only be used by experts.  For almost all
-	circumstances <command>make world</command> is the wrong thing
-	to do, and the procedure described here should be used
-	instead.</para>
-    </warning>
-
-    <sect2 xml:id="canonical-build">
-      <title>Overview of Process</title>
-
-      <para>The build world process assumes an upgrade from an older
-	&os; version using the source of a newer version that was
-	obtained using the instructions in <xref
-	  linkend="synching"/>.</para>
-
-      <para>In &os;, the term <quote>world</quote> includes the
-	kernel, core system binaries, libraries, programming files,
-	and built-in compiler.  The order in which these components
-	are built and installed is important.</para>
-
-      <para>For example, the old compiler might have a bug and not be
-	able to compile the new kernel.  Since the new kernel should
-	be built with the new compiler, the new compiler must be
-	built, but not necessarily installed, before the new kernel is
-	built.</para>
-
-      <para>The new world might rely on new kernel features, so the
-	new kernel must be installed before the new world is
-	installed.  The old world might not run correctly on the new
-	kernel, so the new world must be installed immediately upon
-	installing the new kernel.</para>
-
-      <para>Some configuration changes must be made before the new
-	world is installed, but others might break the old world.
-	Hence, two different configuration upgrade steps are used.
-	For the most part, the update process only replaces or adds
-	files and existing old files are not deleted.  Since this can
-	cause problems, <filename>/usr/src/UPDATING</filename> will
-	indicate if any files need to be manually deleted and at which
-	step to do so.</para>
-
-      <para>These concerns have led to the recommended upgrade
-	sequence described in the following procedure.</para>
-
-      <note>
-	<para>It is a good idea to save the output from running
-	  <command>make</command> to a file.  If something goes wrong,
-	  a copy of the error message can be posted to one of the &os;
-	  mailing lists.</para>
-
-	<para>The easiest way to do this is to use
-	  <command>script</command> with a parameter that specifies
-	  the name of the file to save all output to.  Do not save the
-	  output to <filename>/tmp</filename> as this directory may be
-	  cleared at next reboot.  A better place to save the file is
-	  <filename>/var/tmp</filename>.  Run this command immediately
-	  before rebuilding the world, and then type
-	  <userinput>exit</userinput> when the process has
-	  finished:</para>
-
-	<screen>&prompt.root; <userinput>script <replaceable>/var/tmp/mw.out</replaceable></userinput>
-Script started, output file is /var/tmp/mw.out</screen>
-      </note>
+      <para>This is a quick reference for the typical steps used to
+	update &os; by building from source.  Later sections describe
+	the process in more detail.</para>
 
       <procedure>
-	<title>Overview of Build World Process</title>
+	<step xml:id="updating-src-quick-start-preparing">
+	  <title>Preparing</title>
 
-	<para>The commands used in the build world process should be
-	  run in the order specified here.  This section summarizes
-	  the function of each command.</para>
+	  <para>The very first time a computer is updated from source,
+	    run</para>
 
-	<step>
-	  <para>If the build world process has previously been run on
-	    this system, a copy of the previous build may still exist
-	    in <filename>/usr/obj</filename>.  To
-	    speed up the new build world process, and possibly save
-	    some dependency headaches, remove this directory if it
-	    already exists:</para>
-
-	  <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/*</userinput>
-&prompt.root; <userinput>rm -rf /usr/obj</userinput></screen>
-	</step>
+	  <screen>&prompt.root; <userinput>etcupdate extract</userinput></screen>
 
-	<step>
-	  <para>Compile the new compiler and a few related tools, then
-	    use the new compiler to compile the rest of the new world.
-	    The result is saved to <filename
-	      >/usr/obj</filename>.</para>
-
-	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make buildworld</userinput></screen>
-	</step>
+	  <para>This creates a checkpoint for later comparison and
+	    merging of system settings.</para>
 
-	<step>
-	  <para>Use the new compiler residing in <filename
-	      >/usr/obj</filename> to build the new
-	    kernel, in order to protect against compiler-kernel
-	    mismatches.  This is necessary, as certain memory
-	    structures may have changed, and programs like
-	    <command>ps</command> and <command>top</command> will fail
-	    to work if the kernel and source code versions are not the
-	    same.</para>
-
-	  <screen>&prompt.root; <userinput>make buildkernel</userinput></screen>
+	  <para><emphasis>This step is only done once on a particular
+	    computer.</emphasis>  &man.etcupdate.8; does not need any
+	    additional updates after the first
+	    <emphasis>extract</emphasis>.</para>
 	</step>
 
 	<step>
-	  <para>Install the new kernel and kernel modules, making it
-	    possible to boot with the newly updated kernel.  If
-	    <varname>kern.securelevel</varname> has been raised above
-	    <literal>1</literal> <emphasis>and</emphasis>
-	    <literal>noschg</literal> or similar flags have been set
-	    on the kernel binary, drop the system into single-user
-	    mode first.  Otherwise, this command can be run from
-	    multi-user mode without problems.  See &man.init.8; for
-	    details about <varname>kern.securelevel</varname> and
-	    &man.chflags.1; for details about the various file
-	    flags.</para>
-
-	  <screen>&prompt.root; <userinput>make installkernel</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Drop the system into single-user mode in order to
-	    minimize problems from updating any binaries that are
-	    already running.  It also minimizes any problems from
-	    running the old world on a new kernel.</para>
-
-	  <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
-
-	  <para>Once in single-user mode, run these commands if the
-	    system is formatted with UFS:</para>
-
-	  <screen>&prompt.root; <userinput>mount -u /</userinput>
-&prompt.root; <userinput>mount -a -t ufs</userinput>
-&prompt.root; <userinput>swapon -a</userinput></screen>
-
-	  <para>If the system is instead formatted with ZFS, run these
-	    two commands.  This example assumes a zpool name of
-	    <literal>zroot</literal>:</para>
-
-	  <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput>
-&prompt.root; <userinput>zfs mount -a</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Optional: If a keyboard mapping other than the default
-	    US English is desired, it can be changed with
-	    &man.kbdmap.1;:</para>
-
-	  <screen>&prompt.root; <userinput>kbdmap</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Then, for either file system, if the
-	    <acronym>CMOS</acronym> clock is set to local time (this
-	    is true if the output of &man.date.1; does not show the
-	    correct time and zone), run:</para>
-
-	  <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Remaking the world will not update certain
-	    directories, such as <filename>/etc</filename>,
-	    <filename>/var</filename> and <filename>/usr</filename>,
-	    with new or changed configuration files.  The next step is
-	    to perform some initial configuration file updates
-	    to <filename>/etc</filename> in
-	    preparation for the new world.  The following command
-	    compares only those files that are essential for the
-	    success of <buildtarget>installworld</buildtarget>.  For
-	    instance, this step may add new groups, system accounts,
-	    or startup scripts which have been added to &os; since the
-	    last update.  This is necessary so that the
-	    <buildtarget>installworld</buildtarget> step will be able
-	    to use any new system accounts, groups, and scripts.
-	    Refer to <xref linkend="mergemaster"/> for more detailed
-	    instructions about this command:</para>
-
-	  <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Install the new world and system binaries from
-	    <filename>/usr/obj</filename>.</para>
-
-	  <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make installworld</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Update any remaining configuration files.</para>
-
-	  <screen>&prompt.root; <userinput>mergemaster -iF</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Delete any obsolete files.  This is important as they
-	    may cause problems if left on the disk.</para>
-
-	  <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
-	</step>
-
-	<step>
-	  <para>A full reboot is now needed to load the new kernel and
-	    new world with the new configuration files.</para>
-
-	  <screen>&prompt.root; <userinput>reboot</userinput></screen>
-	</step>
-
-	<step>
-	  <para>Make sure that all installed ports have first been
-	    rebuilt before old libraries are removed using the
-	    instructions in  <xref linkend="ports-upgrading"/>.  When
-	    finished, remove any obsolete libraries to avoid conflicts
-	    with newer ones.  For a more detailed description of this
-	    step, refer to <xref linkend="make-delete-old"/>.</para>
-
-	  <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
+	  <title>Update and Build</title>
+
+	  <screen>&prompt.root; <userinput>svn update /usr/src</userinput>  <co xml:id="updating-src-qs-svnup"/>
+<emphasis>check <filename>/usr/src/UPDATING</filename></emphasis>  <co xml:id="updating-src-qs-review-updating"/>
+&prompt.root; <userinput>cd /usr/src</userinput>          <co xml:id="updating-src-qs-cd"/>
+&prompt.root; <userinput>make -j<replaceable>4</replaceable> buildworld</userinput>  <co xml:id="updating-src-qs-buildworld"/>
+&prompt.root; <userinput>make -j<replaceable>4</replaceable> kernel</userinput>      <co xml:id="updating-src-qs-kernel"/>
+&prompt.root; <userinput>make installworld</userinput>    <co xml:id="updating-src-qs-installworld"/>
+&prompt.root; <userinput>etcupdate</userinput>            <co xml:id="updating-src-qs-etcupdate"/>
+&prompt.root; <userinput>shutdown -r now</userinput>      <co xml:id="updating-src-qs-shutdown"/></screen>
+
+	  <calloutlist>
+	    <callout arearefs="updating-src-qs-svnup">
+	      <para>Get the latest version of the source.  See
+		<xref linkend="updating-src-obtaining-src"/> for
+		more information on obtaining and updating
+		source.</para>
+	    </callout>
+
+	    <callout arearefs="updating-src-qs-review-updating">
+	      <para>Any manual steps required before or after building
+		from source are shown in
+		<filename>/usr/src/UPDATING</filename>.</para>
+	    </callout>
+
+	    <callout arearefs="updating-src-qs-cd">
+	      <para>Go to the source directory.</para>
+	    </callout>
+
+	    <callout arearefs="updating-src-qs-buildworld">
+	      <para>Compile the world, everything except the
+		kernel.</para>
+	    </callout>
+
+	    <callout arearefs="updating-src-qs-kernel">
+	      <para>Compile and install the kernel.  This is
+		equivalent to
+		<buildtarget>buildkernel</buildtarget>
+		<buildtarget>installkernel</buildtarget>.</para>
+	    </callout>
+
+	    <callout arearefs="updating-src-qs-installworld">
+	      <para>Install the world.</para>
+	    </callout>
+
+	    <callout arearefs="updating-src-qs-etcupdate">
+	      <para>Update and merge configuration files in
+		<filename>/etc/</filename>.</para>
+	    </callout>
+
+	    <callout arearefs="updating-src-qs-shutdown">
+	      <para>Restart the system to use the newly-built world
+		and kernel.</para>
+	    </callout>
+	  </calloutlist>
 	</step>
       </procedure>
-
-      <indexterm><primary>single-user mode</primary></indexterm>
-
-      <para>If the system can have a window of down-time, consider
-	compiling the system in single-user mode instead of compiling
-	the system in multi-user mode, and then dropping into
-	single-user mode for the installation.  Reinstalling the
-	system touches a lot of important system files, all the
-	standard system binaries, libraries, and include files.
-	Changing these on a running system, particularly one with
-	active users, is asking for trouble.</para>
     </sect2>
 
-    <sect2 xml:id="src-updating">
-      <title>Configuration Files</title>
-
-      <indexterm>
-	<primary><filename>make.conf</filename></primary>
-      </indexterm>
-
-      <para>This build world process uses several configuration
-	files.</para>
-
-      <para>The <filename>Makefile</filename> located in
-	<filename>/usr/src</filename> describes how the programs that
-	comprise &os; should be built and the order in which they
-	should be built.</para>
-
-      <para>The options available to <command>make</command> are
-	described in &man.make.conf.5; and some common examples are
-	included in
-	<filename>/usr/share/examples/etc/make.conf</filename>.  Any
-	options which are added to <filename>/etc/make.conf</filename>
-	will control the how <command>make</command> runs and builds
-	programs.  These options take effect every time
-	<command>make</command> is used, including compiling
-	applications from the Ports Collection, compiling custom C
-	programs, or building the &os; operating system.  Changes to
-	some settings can have far-reaching and potentially surprising
-	effects.  Read the comments in both locations and keep in mind
-	that the defaults have been chosen for a combination of
-	performance and safety.</para>
+    <sect2 xml:id="updating-src-preparing">
+      <title>Preparing for a Source Update</title>
 
-      <indexterm>
-	<primary><filename>src.conf</filename></primary>
-      </indexterm>
+      <para>If this is the first time that a source update has
+	ever been done on this computer, run
+	<command>etcupdate extract</command> to create a record of
+	system settings for later update and merging.  This step only
+	needs to be done once on a particular computer.</para>
 
-      <para>How the operating system is built from source code is
-	controlled by <filename>/etc/src.conf</filename>.  Unlike
-	<filename>/etc/make.conf</filename>, the contents of
-	<filename>/etc/src.conf</filename> only take effect when the
-	&os; operating system itself is being built.  Descriptions of
-	the many options available for this file are shown in
-	&man.src.conf.5;.  Be cautious about disabling seemingly
-	unneeded kernel modules and build options.  Sometimes there
-	are unexpected or subtle interactions.</para>
+      <para>Read <filename>/usr/src/UPDATING</filename>.  Any manual
+	steps that must be performed before or after an update are
+	described in this file.</para>
     </sect2>
 
-    <sect2 xml:id="make-buildworld">
-      <title>Variables and Targets</title>
-
-      <para>The general format for using <command>make</command> is as
-	follows:</para>
-
-      <screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
-
-      <para>In this example,
-	<option>-<replaceable>x</replaceable></option> is an option
-	passed to <command>make</command>.  Refer to &man.make.1; for
-	examples of the available options.</para>
-
-      <para>To pass a variable, specify the variable name with
-	<option>-D<replaceable>VARIABLE</replaceable></option>.  The
-	behavior of the <filename>Makefile</filename> is controlled by
-	variables.  These can either be set in
-	<filename>/etc/make.conf</filename> or they can be specified
-	when using <command>make</command>.  For example, this
-	variable specifies that profiled libraries should not be
-	built:</para>
-
-      <screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen>
-
-      <para>It corresponds with this setting in
-	<filename>/etc/make.conf</filename>:</para>
-
-      <programlisting>NO_PROFILE=    true     #    Avoid compiling profiled libraries</programlisting>
-
-      <para>The <replaceable>target</replaceable> tells
-	<command>make</command> what to do and the
-	<filename>Makefile</filename> defines the available targets.
-	Some targets are used by the build process to break out the
-	steps necessary to rebuild the system into a number of
-	sub-steps.</para>
-
-      <para>Having separate options is useful for two reasons.  First,
-	it allows for a build that does not affect any components of a
-	running system.  Because of this,
-	<buildtarget>buildworld</buildtarget> can be safely run on a
-	machine running in multi-user mode.  It is still recommended
-	that <buildtarget>installworld</buildtarget> be run in part in
-	single-user mode, though.</para>
-
-      <para>Secondly, it allows <acronym>NFS</acronym> mounts to be
-	used to upgrade multiple machines on a network, as described
-	in <xref linkend="small-lan"/>.</para>
-
-      <para>It is possible to specify <option>-j</option> which will
-	cause <command>make</command> to spawn several simultaneous
-	processes.  Since much of the compiling process is
-	<acronym>I/O</acronym>-bound rather than
-	<acronym>CPU</acronym>-bound, this is useful on both single
-	<acronym>CPU</acronym> and multi-<acronym>CPU</acronym>
-	machines.</para>
-
-      <para>On a single-<acronym>CPU</acronym> machine, run the
-	following command to 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>
-
-      <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
-
-      <para>On a multi-<acronym>CPU</acronym> machine, try values
-	between <literal>6</literal> and <literal>10</literal> to see
-	how they speed things up.</para>
-
-      <indexterm>
-	<primary>rebuilding <quote>world</quote></primary>
-	<secondary>timings</secondary>
-      </indexterm>
-
-      <note>
-	<para>If any variables were specified to <command>make
-	    buildworld</command>, specify the same variables to
-	  <command>make installworld</command>.  However,
-	  <option>-j</option> must <emphasis>never</emphasis> be used
-	  with <buildtarget>installworld</buildtarget>.</para>
-
-	<para>For example, if this command was used:</para>
+    <sect2 xml:id="updating-src-obtaining-src">
+      <title>Updating the Source</title>
+
+      <para>&os; source code is located in
+	<filename>/usr/src/</filename>.  The preferred method of
+	updating this source is through the
+	<application>Subversion</application> version control system.
+	Verify that the source code is under version control:</para>
+
+      <screen>&prompt.root; <userinput>svn info /usr/src</userinput>
+Path: /usr/src
+Working Copy Root Path: /usr/src
+...</screen>
+
+      <para>This indicates that <filename>/usr/src/</filename>
+	is under version control and can be updated with
+	&man.svn.1;:</para>
+
+      <screen xml:id="synching">&prompt.root; <userinput>svn update /usr/src</userinput></screen>
+
+      <para>The update process can take some time if the directory has
+	not been updated recently.  After it finishes, the source code
+	is up to date and the build process described in the next
+	section can begin.</para>
+
+      <note xml:id="updating-src-obtaining-src-checkout">
+	<title>Obtaining the Source</title>
+
+	<para>If the output says
+	  <literal>'/usr/src' is not a working copy</literal>, the
+	  files there are missing or were installed with a different
+	  method.  A new checkout of the source is required.</para>
+
+	<table xml:id="updating-src-obtaining-src-repopath">
+	  <title>&os; Versions and Repository Paths</title>
+
+	  <tgroup cols="3">
+	    <thead>
+	      <row>
+		<entry><command>uname -r</command> Output</entry>
+		<entry>Repository Path</entry>
+		<entry>Description</entry>
+	      </row>
+	    </thead>
+
+	    <tbody>
+	      <row>
+		<entry><literal><replaceable>X.Y</replaceable>-RELEASE</literal></entry>
+		<entry><literal>base/releng/</literal><replaceable>X</replaceable></entry>
+		<entry>The Release version plus only critical security
+		  and bug fix patches.  This branch is recommended
+		  for most users.</entry>
+	      </row>
+
+	      <row>
+		<entry><literal><replaceable>X.Y</replaceable>-STABLE</literal></entry>
+		<entry><literal>base/stable/</literal><replaceable>X</replaceable></entry>
+		<entry>
+		  <para>The Release version plus all additional
+		    development on that branch.
+		    <emphasis>STABLE</emphasis> refers to the
+		    Applications Binary Interface
+		    (<acronym>ABI</acronym>) not changing, so software
+		    compiled for earlier versions still runs.  For
+		    example, software compiled to run on &os; 10.1
+		    will still run on &os; 10-STABLE compiled
+		    later.</para>
+
+		  <para>STABLE branches occasionally have bugs or
+		    incompatibilities which might affect users,
+		    although these are typically fixed quickly.</para>
+		</entry>
+	      </row>
+
+	      <row>
+		<entry><literal><replaceable>X</replaceable>-CURRENT</literal></entry>
+		<entry><literal>base/head/</literal></entry>
+		<entry>The latest unreleased development version of
+		  &os;.  The CURRENT branch can have major bugs or
+		  incompatibilities and is recommended only for
+		  advanced users.</entry>
+	      </row>
+	    </tbody>
+	  </tgroup>
+	</table>
+
+	<para>Determine which version of &os; is being used with
+	  &man.uname.1;:</para>
+
+	<screen>&prompt.root; <userinput>uname -r</userinput>
+10.3-RELEASE</screen>
+
+	<para>Based on
+	  <xref linkend="updating-src-obtaining-src-repopath"/>, the
+	  source used to update <literal>10.3-RELEASE</literal> has a
+	  repository path of <literal>base/releng/10</literal>.  That
+	  path is used when checking out the source:</para>
+
+        <screen>&prompt.root; <userinput>mv /usr/src /usr/src.bak</userinput>  <co xml:id="updating-src-obtaining-src-mv"/>
+&prompt.root; <userinput>svn checkout https://svn.freebsd.org/base/<replaceable>releng/10</replaceable> /usr/src</userinput>  <co xml:id="updating-src-obtaining-src-checkout-cmd"/></screen>
+
+	<calloutlist>
+	  <callout arearefs="updating-src-obtaining-src-mv">
+	    <para>Move the old directory out of the way.  If there are
+	      no local modifications in this directory, it can be
+	      deleted.</para>
+	  </callout>
+
+	  <callout arearefs="updating-src-obtaining-src-checkout-cmd">
+	    <para>The path from
+	      <xref linkend="updating-src-obtaining-src-repopath"/> is
+	      added to the repository <acronym>URL</acronym>.  The
+	      third parameter is the destination directory for the
+	      source code on the local system.</para>
+	  </callout>
+	</calloutlist>
+      </note>
+    </sect2>
 
-	<screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>
+    <sect2 xml:id="updating-src-building">
+      <title>Building from Source</title>
 
-	<para>Install the results with:</para>
+      <para xml:id="makeworld">The <emphasis>world</emphasis>, or all
+	of the operating system except the kernel, is compiled.  This
+	is done first to provide up-to-date tools to build the kernel.
+	Then the kernel itself is built:</para>
 
-	<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
+      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildworld</userinput>
+&prompt.root; <userinput>make buildkernel</userinput></screen>
 
-	<para>Otherwise, the second command will try to install
-	  profiled libraries that were not built during the
-	  <command>make buildworld</command> phase.</para>
-      </note>
-    </sect2>
+      <para>The compiled code is written to
+	<filename>/usr/obj</filename>.</para>
 
-    <sect2 xml:id="mergemaster">
-      <info>
-	<title>Merging Configuration Files</title>
+      <para>These are the basic steps.  Additional options to control
+	the build are described below.</para>
 
-	<authorgroup>
-	  <author>
-	    <personname>
-	      <firstname>Tom</firstname>
-	      <surname>Rhodes</surname>
-	    </personname>
-	    <contrib>Contributed by </contrib>
-	  </author>
-	</authorgroup>
-      </info>
+      <sect3 xml:id="updating-src-building-clean-build">
+	<title>Performing a Clean Build</title>
 
-      <indexterm>
-	<primary>
-	  <command>mergemaster</command>
-	</primary>
-      </indexterm>
+	<para>Some versions of the &os; build system leave
+	  previously-compiled code in the temporary object directory,
+	  <filename>/usr/obj</filename>.  This can speed up later
+	  builds by avoiding recompiling code that has not changed.
+	  To force a clean rebuild of everything, remove
+	  <filename>/usr/obj</filename> before starting a build.
+	  This is roughly equivalent to performing a
+	  <command>make clean</command>, but much faster:</para>
 
-      <para>&os; provides the &man.mergemaster.8; Bourne script to aid
-	in determining the differences between the configuration files
-	in <filename>/etc</filename>, and the configuration files in
-	<filename>/usr/src/etc</filename>.  This is the recommended
-	solution for keeping the system configuration files up to date
-	with those located in the source tree.</para>
-
-      <para>Before using <command>mergemaster</command>, it is
-	recommended to first copy the existing
-	<filename>/etc</filename> somewhere safe.  Include
-	<option>-R</option> which does a recursive copy and
-	<option>-p</option> which preserves times and the ownerships
-	on files:</para>
-
-      <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
-
-      <para>When run, <command>mergemaster</command> builds a
-	temporary root environment, from <filename>/</filename> down,
-	and populates it with various system configuration files.
-	Those files are then compared to the ones currently installed
-	in the system.  Files that differ will be shown in
-	&man.diff.1; format, with the <option>+</option> sign
-	representing added or modified lines, and <option>-</option>
-	representing lines that will be either removed completely or
-	replaced with a new file.  Refer to &man.diff.1; for more
-	information about how file differences are shown.</para>
-
-      <para>Next, <command>mergemaster</command> will display each
-	file that differs, and present options to: delete the new
-	file, referred to as the temporary file, install the temporary
-	file in its unmodified state, merge the temporary file with
-	the currently installed file, or view the results
-	again.</para>
-
-      <para>Choosing to delete the temporary file will tell
-	<command>mergemaster</command> to keep the current file
-	unchanged and to delete the new version.  This option is not
-	recommended.  To get help at any time, type
-	<keycap>?</keycap> at the <command>mergemaster</command>
-	prompt.  If the user chooses to skip a file, it will be
-	presented again after all other files have been dealt
-	with.</para>
-
-      <para>Choosing to install the unmodified temporary file will
-	replace the current file with the new one.  For most
-	unmodified files, this is the best option.</para>
-
-      <para>Choosing to merge the file will present a text editor with
-	the contents of both files open.  The files can be merged by
-	reviewing both files side by side on the screen and choosing
-	parts from both to create a finished product.  When the files
-	are compared side by side, <keycap>l</keycap> selects the left
-	contents and <keycap>r</keycap> selects contents from the
-	right.  The final output will be a file consisting of both
-	parts, which can then be installed.  This option is
-	customarily used for files where settings have been modified
-	by the user.</para>
-
-      <para>Choosing to view the results again will redisplay the file
-	differences.</para>
-
-      <para>After <command>mergemaster</command> is done with the
-	system files, it will prompt for other options.  It may prompt
-	to rebuild the password file and will finish up with an option
-	to remove left-over temporary files.</para>
-<!--
-Probably not needed as changes should be minimal and mergemaster does
-a good job of merging.
-	<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 rebuilding world entails frequently
-	    updating <filename>/etc</filename>
-	    as well, which can be a bit of a chore.</para>
-
-	  <para>To speed up this process, use the following
-	    procedure to keep a copy of the last set of changed files
-	    that were merged into <filename>/etc</filename>.</para>
-
-	  <procedure>
-	    <step>
-	      <para>Make the world as normal.  When updating
-		<filename>/etc</filename> and the
-		other directories, give the target directory a name
-		based on the current date:</para>
-
-	      <screen>&prompt.root; <userinput>mkdir /var/tmp/root-20130214</userinput>
-&prompt.root; <userinput>cd /usr/src/etc</userinput>
-&prompt.root; <userinput>make DESTDIR=/var/tmp/root-20130214 \
-    distrib-dirs distribution</userinput></screen>
-	    </step>
-
-	    <step>
-	      <para>Merge in the changes from this directory as
-		outlined above.  <emphasis>Do not</emphasis> remove
-		the <filename>/var/tmp/root-20130214</filename>
-		directory when you have finished.</para>
-	    </step>
-
-	    <step>
-	      <para>After downloading the latest version of the
-		source and remaking it, follow step 1.  Create a new
-		directory, which reflects the new date.  This example
-		uses
-		<filename>/var/tmp/root-20130221</filename>.</para>
-	    </step>
-
-	    <step>
-	      <para>Use &man.diff.1; to see the differences that have
-		been made in the intervening week by creating a
-		recursive diff between the two directories:</para>
-
-	      <screen>&prompt.root; <userinput>cd /var/tmp</userinput>
-&prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen>
-
-	      <para>Typically, this will be a much smaller set of
-		differences than those between
-		<filename>/var/tmp/root-20130221/etc</filename> and
-		<filename>/etc</filename>.  Because the set of
-		differences is smaller, it is easier to migrate those
-		changes across into <filename>/etc</filename>.</para>
-	    </step>
-
-	    <step>
-	      <para>When finished, remove the older of the two
-		<filename>/var/tmp/root-*</filename>
-		directories:</para>
-
-	      <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen>
-	    </step>
-
-	    <step>
-	      <para>Repeat this process whenever merging
-		in changes to <filename>/etc</filename>.</para>
-	    </step>
-	  </procedure>
-
-	  <para>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>
+	<screen>&prompt.root; <userinput>rm -rf /usr/obj/*</userinput></screen>
+      </sect3>
 
-    <sect2 xml:id="make-delete-old">
-      <info>
-	<title>Deleting Obsolete Files and Libraries</title>
+      <sect3 xml:id="updating-src-building-jobs">
+	<title>Setting the Number of Jobs</title>
 
-	<authorgroup>
-	  <author>
-	    <personname>
-	      <firstname>Anton</firstname>
-	      <surname>Shterenlikht</surname>
-	    </personname>
-	    <contrib>Based on notes provided by </contrib>
-	  </author>
-	</authorgroup>
-      </info>
+	<para>Increasing the number of build jobs on multi-core
+	  processors can improve build speed.  Determine the number of
+	  cores with <command>sysctl hw.ncpu</command>.  Processors
+	  vary, as do the build systems used with different versions
+	  of &os;, so testing is the only sure method to tell how a
+	  different number of jobs affects the build speed.  For a
+	  starting point, consider values between half and double the
+	  number of cores.  The number of jobs is specified with
+	  <option>-j</option>.</para>
 
-      <indexterm>
-	<primary>Deleting obsolete files and directories</primary>
-      </indexterm>
+	<example xml:id="updating-src-building-jobs-example">
+	  <title>Increasing the Number of Build Jobs</title>
 
-      <para>As a part of the &os; development lifecycle, files and
-	their contents occasionally become obsolete.  This may be
-	because functionality is implemented elsewhere, the version
-	number of the library has changed, or it was removed from the
-	system entirely.  These obsoleted files, libraries, and
-	directories should be removed when updating the system.
-	This ensures that the system is not cluttered with old files
-	which take up unnecessary space on the storage and backup
-	media.  Additionally, if the old library has a security or
-	stability issue, the system should be updated to the newer
-	library to keep it safe and to prevent crashes caused by the
-	old library.  Files, directories, and libraries which are
-	considered obsolete are listed in
-	<filename>/usr/src/ObsoleteFiles.inc</filename>.  The
-	following instructions should be used to remove obsolete files
-	during the system upgrade process.</para>
-
-      <para>After the <command>make installworld</command> and the
-	subsequent <command>mergemaster</command> have finished
-	successfully, check for obsolete files and libraries:</para>
+	  <para>Building the world and kernel with four jobs:</para>
 
-      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make check-old</userinput></screen>
+	  <screen>&prompt.root; <userinput>make -j4 buildworld buildkernel</userinput></screen>
+	</example>
+      </sect3>
 
-      <para>If any obsolete files are found, they can be deleted using
-	the following command:</para>
+      <sect3 xml:id="updating-src-building-go-fast">
+	<title>go-fast</title>
 
-      <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
+	<para>Go-fast: Describe other go-fast options like NO_CLEAN
+	  here.  Preferably avoid having different sections for
+	  different versions of &os;.</para>
+      </sect3>
 
-      <para>A prompt is displayed before deleting each obsolete file.
-	To skip the prompt and let the system remove these files
-	automatically, use
-	<varname>BATCH_DELETE_OLD_FILES</varname>:</para>
+      <sect3 xml:id="updating-src-building-only-kernel">
+	<title>Building Only the Kernel</title>
 
-      <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
+	<para>A <buildtarget>buildworld</buildtarget> must be
+	  completed if the source code has changed.  After that, a
+	  <buildtarget>buildkernel</buildtarget> to build a kernel can
+	  be run at any time.  To build just the kernel:</para>
 
-      <para>The same goal can be achieved by piping these commands
-	through <command>yes</command>:</para>
+	<screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildkernel</userinput></screen>
+      </sect3>
 
-      <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
+      <sect3 xml:id="updating-src-building-custom-kernel">
+	<title>Building a Custom Kernel</title>
+
+	<para>The standard &os; kernel is based on a
+	  <emphasis>kernel config file</emphasis> called
+	  <filename>GENERIC</filename>.  The
+	  <filename>GENERIC</filename> kernel includes the most
+	  commonly-needed device drivers and options.  Sometimes it
+	  is useful or necessary to build a custom kernel, adding or
+	  removing device drivers or options to fit a specific
+	  need.</para>
+
+	<para>For example, someone developing a small embedded
+	  computer with severely limited <acronym>RAM</acronym> could
+	  remove unneeded device drivers or options to make the kernel
+	  slightly smaller.</para>
+
+	<para>Kernel config files are located in
+	  <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/</filename>,
+	  where <replaceable>arch</replaceable> is the output from
+	  <command>uname -m</command>.  On most computers, that is
+	  <literal>amd64</literal>, giving a config file directory of
+	  <filename>/usr/src/sys/<replaceable>amd64</replaceable>/conf/</filename>.</para>
+
+	<para>A custom config file can be created by copying the
+	  <filename>GENERIC</filename> config file.  In this example,
+	  the new custom kernel is for a storage server, so is named
+	  <filename>STORAGESERVER</filename>:</para>
+
+	<screen>&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput>
+&prompt.root; <userinput>cp GENERIC STORAGESERVER</userinput></screen>
+
+	<para><filename>STORAGESERVER</filename> is then edited,
+	  adding or removing devices or options as shown in
+	  &man.config.5;.</para>
+
+	<para>The custom kernel is built by setting
+	  <varname>KERNCONF</varname> to the kernel config file on the
+	  command line:</para>
+
+	<screen>&prompt.root; <userinput>make buildkernel KERNCONF=STORAGESERVER</userinput></screen>
+      </sect3>
+    </sect2>
 
-      <warning>
-	<title>Warning</title>
-
-	<para>Deleting obsolete files will break applications that
-	  still depend on those obsolete files.  This is especially
-	  true for old libraries.  In most cases, the programs, ports,
-	  or libraries that used the old library need to be recompiled
-	  before <command>make delete-old-libs</command> is
-	  executed.</para>
-      </warning>
+    <sect2 xml:id="updating-src-installing">
+      <title>Installing the Compiled Code</title>
 
-      <para>Utilities for checking shared library dependencies include
-	<package>sysutils/libchk</package> and
-	<package>sysutils/bsdadminscripts</package>.</para>
+      <para>After the <buildtarget>buildworld</buildtarget> and
+	<buildtarget>buildkernel</buildtarget> steps have been
+	completed, the new kernel and world are installed:</para>
 
-      <para>Obsolete shared libraries can conflict with newer
-	libraries, causing messages like these:</para>
+      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make installkernel installworld</userinput></screen>
 
-      <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
-/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
+      <para>If a custom kernel was built, <varname>KERNCONF</varname>
+	must also be set to use the new custom kernel:</para>
 
-      <para>To solve these problems, determine which port installed
-	the library:</para>
+      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make installkernel installworld KERNCONF=STORAGESERVER</userinput></screen>
+    </sect2>
 
-      <screen>&prompt.root; <userinput>pkg which /usr/local/lib/libtiff.so</userinput>
-  /usr/local/lib/libtiff.so was installed by package tiff-3.9.4
-&prompt.root; <userinput>pkg which /usr/local/lib/libXext.so</userinput>
-  /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen>
+    <sect2 xml:id="updating-src-completing">
+      <title>Completing the Update</title>
 
-      <para>Then deinstall, rebuild, and reinstall the port.  To
-	automate this process,
-	<package>ports-mgmt/portmaster</package> can be used.  After
-	all ports are rebuilt and no longer use the old libraries,
-	delete the old libraries using the following command:</para>
+      <para>A few final tasks complete the update.  Any modified
+	configuration files are merged with the new versions, outdated
+	libraries are located and removed, then the system is
+	restarted.</para>
 
-      <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
+      <sect3 xml:id="updating-src-completing-merge-etcupdate">
+	<title>Merging Configuration Files with
+	  <application>etcupdate</application></title>
 
-      <para>If something goes wrong, it is easy to rebuild a
-	particular piece of the system.  For example, if
-	<filename>/etc/magic</filename> was accidentally deleted as
-	part of the upgrade or merge of <filename>/etc</filename>,
-	<command>file</command> will stop working.  To fix this,
-	run:</para>
+	<para><application>etcupdate</application> provides an easy
+	  way to merge changes that have been made to system
+	  configuration files with new versions of those files.</para>
 
-      <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
-&prompt.root; <userinput>make all install</userinput></screen>
-    </sect2>
+	<para><command>etcupdate</command></para>
+      </sect3>
 
-    <sect2 xml:id="updating-questions">
-      <title>Common Questions</title>
+      <sect3 xml:id="updating-src-completing-merge-mergemaster">
+	<title xml:id="mergemaster">Merging Configuration Files with
+	  <application>mergemaster</application></title>
 
-      <variablelist>
-	<varlistentry>
-	  <term>Do I need to re-make the world for every
-	      change?</term>
+	<para><command>mergemaster -Ui</command></para>
+      </sect3>
 
-	  <listitem>
-	    <para>It depends upon the nature of the change.  For
-	      example, if <application>svn</application> only shows
-	      the following files as being updated:</para>
-
-	    <screen><filename>src/games/factor/factor.c</filename>
-<filename>src/games/fortune/fortune/fortune.c</filename>
-<filename>src/usr.sbin/bsdinstall/distextract/distextract.c</filename>
-<filename>src/usr.sbin/bsdinstall/partedit/diskeditor.c</filename>
-<filename>src/share/man/man7/intro.7</filename></screen>
-
-	    <para>it probably is not worth rebuilding the entire
-	      world.  Instead, go into the appropriate sub-directories
-	      and run <command>make all install</command>.  But if
-	      something major changes, such as
-	      <filename>src/lib/libc/stdlib</filename>, a complete rebuild of
-	      world is highly recommended.</para>
-
-	    <para>Some users rebuild world every fortnight and let
-	      changes accumulate over that fortnight.  Others only
-	      re-make those things that have changed and are careful
-	      to spot all the dependencies.  It all depends on how
-	      often a user wants to upgrade and whether they are
-	      tracking &os.stable; or &os.current;.</para>
-	  </listitem>
-	</varlistentry>
+      <sect3 xml:id="updating-src-completing-check-old">
+	<title>Checking for Outdated Files and Libraries</title>
 
-	<varlistentry>
-	  <term>What would cause a compile to fail with lots of
-	    signal 11<indexterm>
-	      <primary>signal 11</primary>
-	    </indexterm>
-	    (or other signal number) errors?</term>
+	<para>Some obsolete files or directories can remain after an
+	  update.  These files can be located:</para>
 
-	  <listitem>
-	    <para>This normally indicates a hardware problem.
-	      Building world is an effective way to stress test
-	      hardware, especially memory.  A sure indicator of a
-	      hardware issue is when <application>make</application>
-	      is restarted and it dies at a different point in the
-	      process.</para>
-
-	    <para>To resolve this error, swap out the components in
-	      the machine, starting with RAM, to determine which
-	      component is failing.</para>
-	  </listitem>
-	</varlistentry>
+	<screen>&prompt.root; <userinput>make check-old</userinput></screen>
 
-	<varlistentry>
-	  <term>Can <filename>/usr/obj</filename>
-	      be removed when finished?</term>
+	<para>and deleted:</para>
 
-	  <listitem>
-	    <para>This directory contains all the object files that
-	      were produced during the compilation phase.  Normally,
-	      one of the first steps in the <command>make
-		buildworld</command> process is to remove this
-	      directory and start afresh.  Keeping
-	      <filename>/usr/obj</filename> around when finished makes
-	      little sense, and its removal frees up a approximately
-	      2GB of disk space.</para>
-	  </listitem>
-	</varlistentry>
+	<screen>&prompt.root; <userinput>make delete-old</userinput></screen>
 
-	<varlistentry>
-	  <term>Can interrupted builds be resumed?</term>
+	<para>Some obsolete libraries can also remain.  These can be
+	  detected with:</para>
 
-	  <listitem>
-	    <para>This depends on how far into the process the
-	      problem occurs.  In general, <command>make
-		buildworld</command> builds new copies of essential
-	      tools and the system libraries.  These tools and
-	      libraries are then installed, used to rebuild
-	      themselves, and are installed again.  The rest of the
-	      system is then rebuilt with the new system
-	      tools.</para>
-
-	    <para>During the last stage, it is fairly safe to run
-	      these commands as they will not undo the work of the
-	      previous <command>make buildworld</command>:</para>
-
-	    <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>
-
-	    <para>If this message appears:</para>
-
-	    <screen>--------------------------------------------------------------
-Building everything..
---------------------------------------------------------------</screen>
-
-	    <para>in the <command>make buildworld</command> output,
-	      it is probably fairly safe to do so.</para>
-
-	    <para>If that message is not displayed, it is always
-	      better to be safe than sorry and to restart the build
-	      from scratch.</para>
-	  </listitem>
-	</varlistentry>
+	<screen>&prompt.root; <userinput>make check-old-libs</userinput></screen>
 
-	<varlistentry>
-	  <term>Is it possible to speed up making the world?</term>
+	<para>and deleted with</para>
 
-	  <listitem>
-	    <para>Several actions can speed up the build world
-	      process.  For example, the entire process can be run
-	      from single-user mode.  However, this will prevent users
-	      from having access to the system until the process is
-	      complete.</para>
-
-	    <para>Careful file system design or the use of ZFS
-	      datasets can make a difference.  Consider putting
-	      <filename>/usr/src</filename> and
-	      <filename>/usr/obj</filename> on
-	      separate file systems.  If possible, place the file
-	      systems on separate disks on separate disk controllers.
-	      When mounting <filename
-		>/usr/src</filename>, use
-	      <option>noatime</option> which prevents the file system
-	      from recording the file access time.  If <filename
-		>/usr/src</filename> is not on its
-	      own file system, consider remounting <filename
-		>/usr</filename> with
-	      <option>noatime</option>.</para>
-
-	    <para>The file system holding <filename
-		>/usr/obj</filename> can be mounted
-	      or remounted with <option>async</option> so that disk
-	      writes happen asynchronously.  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 provide a dramatic performance
-	      boost.</para>
-
-	    <warning>
-	      <para>Keep in mind that this option makes the file
-		system more fragile.  With this option, there is an
-		increased chance that, should power fail, the file
-		system will be in an unrecoverable state when the
-		machine restarts.</para>
-
-	      <para>If <filename>/usr/obj</filename> is the only
-		directory on this file system, this is not a problem.
-		If you have other, valuable data on the same file
-		system, ensure that there are verified backups before
-		enabling this option.</para>
-	    </warning>
-
-	    <para>Turn off profiling by setting
-	      <quote>NO_PROFILE=true</quote> in
-	      <filename>/etc/make.conf</filename>.</para>
-
-	    <para>Pass <option>-j<replaceable>n</replaceable></option>
-	      to &man.make.1; to run multiple processes in parallel.
-	      This usually helps on both single- and multi-processor
-	      machines.</para>
-	  </listitem>
-	</varlistentry>
+	<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
 
-	<varlistentry>
-	  <term>What if something goes wrong?</term>
+	<para>Programs which were still using those old libraries will
+	  stop working when the library has been deleted.  These
+	  programs must be rebuilt or replaced after deleting the old
+	  libraries.</para>
 
-	  <listitem>
-	    <para>First, make absolutely sure that the environment has
-	      no extraneous cruft from earlier builds:</para>
+	<tip>
+	  <para>When all the old files or directories are known to be
+	    safe to delete, pressing <keycap>y</keycap> and
+	    <keycap>Enter</keycap> to delete each file can be avoided
+	    by setting <varname>BATCH_DELETE_OLD_FILES</varname> in
+	    the command.  For example:</para>
 
-	    <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
-&prompt.root; <userinput>rm -rf /usr/obj/usr</userinput>
-&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make cleandir</userinput>
-&prompt.root; <userinput>make cleandir</userinput></screen>
+	  <screen>&prompt.root; <userinput>make BATCH_DELETE_OLD_FILES=yes delete-old-libs</userinput></screen>
+	</tip>
+      </sect3>
 
-	    <para>Yes, <command>make cleandir</command> really should
-	      be run twice.</para>
+      <sect3 xml:id="updating-src-completing-restart">
+	<title>Restarting After the Update</title>
 
-	    <para>Then, restart the whole process, starting with
-	      <command>make buildworld</command>.</para>
+	<para>The last step after updating is to restart the computer
+	  so all the changes take effect:</para>
 
-	    <para>If problems persist, send the error and the output
-	      of <command>uname -a</command> to &a.questions;.  Be
-	      prepared to answer other questions about the
-	      setup!</para>
-	  </listitem>
-	</varlistentry>
-      </variablelist>
+	<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
+      </sect3>
     </sect2>
   </sect1>