View All Attachments for Bug 206866

Attachment #166466
Patch to update handbook to replace mergemaster(8) with etcupdate(8)	patch	2016-02-03 00:51:36 UTC	18.54 KB	no flags	Details

Attachment #166467
QA: Successully built makeworld.html section from handbook (with proposed changes)	text/html	2016-02-03 00:53:34 UTC	48.60 KB	no flags	Details

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /><title>23.6. Rebuilding World</title><link rel="stylesheet" type="text/css" href="docbook.css" /><link rev="made" href="mailto:doc@FreeBSD.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="FreeBSD Handbook" /><link rel="up" href="updating-upgrading.html" title="Chapter 23. Updating and Upgrading FreeBSD" /><link rel="prev" href="synching.html" title="23.5. Synchronizing Source" /><link rel="next" href="small-lan.html" title="23.7. Tracking for Multiple Machines" /><link rel="copyright" href="legalnotice.html" title="Copyright" /><script xmlns="" type="text/javascript" src="/layout/js/google.js"></script></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">23.6. Rebuilding World</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="synching.html">Prev</a> </td><th width="60%" align="center">Chapter 23. Updating and Upgrading FreeBSD</th><td width="20%" align="right"> <a accesskey="n" href="small-lan.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div xmlns="" class="titlepage"><div><div><h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a id="makeworld"></a>23.6. Rebuilding World</h2></div></div></div><a id="idp79010944" class="indexterm"></a><p>Once the local source tree is synchronized against a
      particular version of FreeBSD such as FreeBSD-STABLE or FreeBSD-CURRENT,
      the source tree can be used to rebuild the system.  This process
      is known as rebuilding world.</p><p><span class="emphasis"><em>Before</em></span> rebuilding world, be sure to
      perform the following tasks:</p><div class="procedure"><a id="idp79012992"></a><div class="procedure-title">Procedure 23.1. Perform These Tasks <span class="emphasis"><em>Before</em></span>
	Building World</div><ol class="procedure" type="1"><li class="step"><p>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
	  <span class="emphasis"><em>before</em></span> 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!</p></li><li class="step"><a id="idp79015424" class="indexterm"></a><p>Review the recent <a class="link" href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-stable" target="_top">freebsd-stable</a> or <a class="link" href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-current" target="_top">freebsd-current</a>
	  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 <span class="quote">&#8220;<span class="quote">all clear</span>&#8221;</span> 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.</p></li><li class="step"><p>If you have not previously performed an 
	  <code class="buildtarget">installworld</code> using the
	  <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> utility to perform the post install
	  merging of the configuration files, then it will need to be
	  bootstrapped.  For details on how to perform the
	  bootstrapping procedure, or how to determine whether it is
	  required, see <a class="xref" href="makeworld.html#etcupdate-bootstrap" title="23.6.4.1. Bootstrapping etcupdate (First time only)">Section 23.6.4.1, &#8220;Bootstrapping <code class="command">etcupdate</code> (First time only)&#8221;</a>.
	</p></li><li class="step"><p>Read <code class="filename">/usr/src/UPDATING</code> 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 <code class="filename">UPDATING</code> contradicts
	  any steps in this chapter, the instructions in
	  <code class="filename">UPDATING</code> take precedence and should be
	  followed.</p></li></ol></div><div xmlns="" class="warning"><h3 class="admontitle">Do Not Use <code xmlns="http://www.w3.org/1999/xhtml" class="command">make world</code>: </h3><p xmlns="http://www.w3.org/1999/xhtml">Some older documentation recommends using <code class="command">make
	  world</code>.  However, that command skips some important
	steps and should only be used by experts.  For almost all
	circumstances <code class="command">make world</code> is the wrong thing
	to do, and the procedure described here should be used
	instead.</p></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="canonical-build"></a>23.6.1. Overview of Process</h3></div></div></div><p>The build world process assumes an upgrade from an older
	FreeBSD version using the source of a newer version that was
	obtained using the instructions in <a class="xref" href="synching.html" title="23.5. Synchronizing Source">Section 23.5, &#8220;Synchronizing Source&#8221;</a>.</p><p>In FreeBSD, the term <span class="quote">&#8220;<span class="quote">world</span>&#8221;</span> 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.</p><p>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.</p><p>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.</p><p>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, <code class="filename">/usr/src/UPDATING</code> will
	indicate if any files need to be manually deleted and at which
	step to do so.</p><p>These concerns have led to the recommended upgrade
	sequence described in the following procedure.</p><div xmlns="" class="note"><h3 class="admontitle">Note: </h3><p xmlns="http://www.w3.org/1999/xhtml">It is a good idea to save the output from running
	  <code class="command">make</code> to a file.  If something goes wrong,
	  a copy of the error message can be posted to one of the FreeBSD
	  mailing lists.</p><p xmlns="http://www.w3.org/1999/xhtml">The easiest way to do this is to use
	  <code class="command">script</code> with a parameter that specifies
	  the name of the file to save all output to.  Do not save the
	  output to <code class="filename">/tmp</code> as this directory may be
	  cleared at next reboot.  A better place to save the file is
	  <code class="filename">/var/tmp</code>.  Run this command immediately
	  before rebuilding the world, and then type
	  <strong class="userinput"><code>exit</code></strong> when the process has
	  finished:</p><pre xmlns="http://www.w3.org/1999/xhtml" class="screen"><code class="prompt">#</code> <strong class="userinput"><code>script <em class="replaceable"><code>/var/tmp/mw.out</code></em></code></strong>
Script started, output file is /var/tmp/mw.out</pre></div><div class="procedure"><a id="idp79033216"></a><div class="procedure-title">Procedure 23.2. Overview of Build World Process</div><p>The commands used in the build world process should be
	  run in the order specified here.  This section summarizes
	  the function of each command.</p><ol class="procedure" type="1"><li class="step"><p>If the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> utility has not previously
	    been used to perform the post-<code class="buildtarget">installworld</code>
	    merging of configuration files within <code class="filename">/etc/</code>,
	    then it will need to be bootstrapped using a copy of the
	    FreeBSD source tree which matches the <span class="emphasis"><em>currently</em></span>
	    installed system (pre-upgrade):</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate extract -s <em class="replaceable"><code>/PATH/TO/PREVIOUS/SOURCE/TREE</code></em></code></strong></pre></li><li class="step"><p>If the build world process has previously been run on
	    this system, a copy of the previous build may still exist
	    in <code class="filename">/usr/obj</code>.  To
	    speed up the new build world process, and possibly save
	    some dependency headaches, remove this directory if it
	    already exists:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>chflags -R noschg /usr/obj/*</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>rm -rf /usr/obj</code></strong></pre></li><li class="step"><p>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 <code class="filename">/usr/obj</code>.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make buildworld</code></strong></pre></li><li class="step"><p>Use the new compiler residing in <code class="filename">/usr/obj</code> 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
	    <code class="command">ps</code> and <code class="command">top</code> will fail
	    to work if the kernel and source code versions are not the
	    same.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make buildkernel</code></strong></pre></li><li class="step"><p>Install the new kernel and kernel modules, making it
	    possible to boot with the newly updated kernel.  If
	    <code class="varname">kern.securelevel</code> has been raised above
	    <code class="literal">1</code> <span class="emphasis"><em>and</em></span>
	    <code class="literal">noschg</code> 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 <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=init&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">init</span>(8)</span></a> for
	    details about <code class="varname">kern.securelevel</code> and
	    <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=chflags&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">chflags</span>(1)</span></a> for details about the various file
	    flags.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make installkernel</code></strong></pre></li><li class="step"><p>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.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>shutdown now</code></strong></pre><p>Once in single-user mode, run these commands if the
	    system is formatted with UFS:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>mount -u /</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>mount -a -t ufs</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>swapon -a</code></strong></pre><p>If the system is instead formatted with ZFS, run these
	    two commands.  This example assumes a zpool name of
	    <code class="literal">zroot</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>zfs set readonly=off zroot</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>zfs mount -a</code></strong></pre></li><li class="step"><p>Optional: If a keyboard mapping other than the default
	    US English is desired, it can be changed with
	    <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=kbdmap&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">kbdmap</span>(1)</span></a>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>kbdmap</code></strong></pre></li><li class="step"><p>Then, for either file system, if the
	    <acronym class="acronym">CMOS</acronym> clock is set to local time (this
	    is true if the output of <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=date&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">date</span>(1)</span></a> does not show the
	    correct time and zone), run:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>adjkerntz -i</code></strong></pre></li><li class="step"><p>Remaking the world will not update certain
	    directories, such as <code class="filename">/etc</code>,
	    <code class="filename">/var</code> and <code class="filename">/usr</code>,
	    with new or changed configuration files.  The next step is
	    to perform some initial configuration file updates
	    to <code class="filename">/etc</code> in
	    preparation for the new world.  The following command
	    compares only those files that are essential for the
	    success of <code class="buildtarget">installworld</code>.  For
	    instance, this step may add new groups, system accounts,
	    or startup scripts which have been added to FreeBSD since the
	    last update.  This is necessary so that the
	    <code class="buildtarget">installworld</code> step will be able
	    to use any new system accounts, groups, and scripts.
	    Refer to <a class="xref" href="makeworld.html#etcupdate" title="23.6.4. Merging Configuration Files">Section 23.6.4, &#8220;Merging Configuration Files&#8221;</a> for more detailed
	    instructions about this command:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate -p</code></strong></pre></li><li class="step"><p>Install the new world and system binaries from
	    <code class="filename">/usr/obj</code>.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make installworld</code></strong></pre></li><li class="step"><p>Update any remaining configuration files.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate</code></strong></pre></li><li class="step"><p>Delete any obsolete files.  This is important as they
	    may cause problems if left on the disk.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make delete-old</code></strong></pre></li><li class="step"><p>A full reboot is now needed to load the new kernel and
	    new world with the new configuration files.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>reboot</code></strong></pre></li><li class="step"><p>Make sure that all installed ports have first been
	    rebuilt before old libraries are removed using the
	    instructions in  <a class="xref" href="ports-using.html#ports-upgrading" title="4.5.3. Upgrading Ports">Section 4.5.3, &#8220;Upgrading Ports&#8221;</a>.  When
	    finished, remove any obsolete libraries to avoid conflicts
	    with newer ones.  For a more detailed description of this
	    step, refer to <a class="xref" href="makeworld.html#make-delete-old" title="23.6.5. Deleting Obsolete Files and Libraries">Section 23.6.5, &#8220;Deleting Obsolete Files and Libraries&#8221;</a>.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make delete-old-libs</code></strong></pre></li></ol></div><a id="idp79087104" class="indexterm"></a><p>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.</p></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="src-updating"></a>23.6.2. Configuration Files</h3></div></div></div><a id="idp79088896" class="indexterm"></a><p>This build world process uses several configuration
	files.</p><p>The <code class="filename">Makefile</code> located in
	<code class="filename">/usr/src</code> describes how the programs that
	comprise FreeBSD should be built and the order in which they
	should be built.</p><p>The options available to <code class="command">make</code> are
	described in <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=make.conf&amp;sektion=5"><span class="citerefentry"><span class="refentrytitle">make.conf</span>(5)</span></a> and some common examples are
	included in
	<code class="filename">/usr/share/examples/etc/make.conf</code>.  Any
	options which are added to <code class="filename">/etc/make.conf</code>
	will control the how <code class="command">make</code> runs and builds
	programs.  These options take effect every time
	<code class="command">make</code> is used, including compiling
	applications from the Ports Collection, compiling custom C
	programs, or building the FreeBSD 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.</p><a id="idp79098624" class="indexterm"></a><p>How the operating system is built from source code is
	controlled by <code class="filename">/etc/src.conf</code>.  Unlike
	<code class="filename">/etc/make.conf</code>, the contents of
	<code class="filename">/etc/src.conf</code> only take effect when the
	FreeBSD operating system itself is being built.  Descriptions of
	the many options available for this file are shown in
	<a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=src.conf&amp;sektion=5"><span class="citerefentry"><span class="refentrytitle">src.conf</span>(5)</span></a>.  Be cautious about disabling seemingly
	unneeded kernel modules and build options.  Sometimes there
	are unexpected or subtle interactions.</p></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="make-buildworld"></a>23.6.3. Variables and Targets</h3></div></div></div><p>The general format for using <code class="command">make</code> is as
	follows:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -<em class="replaceable"><code>x</code></em> -D<em class="replaceable"><code>VARIABLE</code></em> <em class="replaceable"><code>target</code></em></code></strong></pre><p>In this example,
	<code class="option">-<em class="replaceable"><code>x</code></em></code> is an option
	passed to <code class="command">make</code>.  Refer to <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=make&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> for
	examples of the available options.</p><p>To pass a variable, specify the variable name with
	<code class="option">-D<em class="replaceable"><code>VARIABLE</code></em></code>.  The
	behavior of the <code class="filename">Makefile</code> is controlled by
	variables.  These can either be set in
	<code class="filename">/etc/make.conf</code> or they can be specified
	when using <code class="command">make</code>.  For example, this
	variable specifies that profiled libraries should not be
	built:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -DNO_PROFILE <em class="replaceable"><code>target</code></em></code></strong></pre><p>It corresponds with this setting in
	<code class="filename">/etc/make.conf</code>:</p><pre class="programlisting">NO_PROFILE=    true     #    Avoid compiling profiled libraries</pre><p>The <em class="replaceable"><code>target</code></em> tells
	<code class="command">make</code> what to do and the
	<code class="filename">Makefile</code> 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.</p><p>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,
	<code class="buildtarget">buildworld</code> can be safely run on a
	machine running in multi-user mode.  It is still recommended
	that <code class="buildtarget">installworld</code> be run in part in
	single-user mode, though.</p><p>Secondly, it allows <acronym class="acronym">NFS</acronym> mounts to be
	used to upgrade multiple machines on a network, as described
	in <a class="xref" href="small-lan.html" title="23.7. Tracking for Multiple Machines">Section 23.7, &#8220;Tracking for Multiple Machines&#8221;</a>.</p><p>It is possible to specify <code class="option">-j</code> which will
	cause <code class="command">make</code> to spawn several simultaneous
	processes.  Since much of the compiling process is
	<acronym class="acronym">I/O</acronym>-bound rather than
	<acronym class="acronym">CPU</acronym>-bound, this is useful on both single
	<acronym class="acronym">CPU</acronym> and multi-<acronym class="acronym">CPU</acronym>
	machines.</p><p>On a single-<acronym class="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.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -j4 buildworld</code></strong></pre><p>On a multi-<acronym class="acronym">CPU</acronym> machine, try values
	between <code class="literal">6</code> and <code class="literal">10</code> to see
	how they speed things up.</p><a id="idp79142272" class="indexterm"></a><div xmlns="" class="note"><h3 class="admontitle">Note: </h3><p xmlns="http://www.w3.org/1999/xhtml">If any variables were specified to <code class="command">make
	    buildworld</code>, specify the same variables to
	  <code class="command">make installworld</code>.  However,
	  <code class="option">-j</code> must <span class="emphasis"><em>never</em></span> be used
	  with <code class="buildtarget">installworld</code>.</p><p xmlns="http://www.w3.org/1999/xhtml">For example, if this command was used:</p><pre xmlns="http://www.w3.org/1999/xhtml" class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -DNO_PROFILE buildworld</code></strong></pre><p xmlns="http://www.w3.org/1999/xhtml">Install the results with:</p><pre xmlns="http://www.w3.org/1999/xhtml" class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -DNO_PROFILE installworld</code></strong></pre><p xmlns="http://www.w3.org/1999/xhtml">Otherwise, the second command will try to install
	  profiled libraries that were not built during the
	  <code class="command">make buildworld</code> phase.</p></div></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="etcupdate"></a>23.6.4. Merging Configuration Files</h3></div><div><span class="authorgroup">Originally written for the mergemaster(8) utility by <span xmlns="http://www.w3.org/1999/xhtml" class="author"><span class="firstname">Tom</span> <span class="surname">Rhodes</span></span>. </span></div><div><span class="authorgroup">Modified to use the newer etcupdate(8) utility by <span xmlns="http://www.w3.org/1999/xhtml" class="author"><span class="firstname">Ben</span> <span class="surname">Woods</span></span>. </span></div></div></div><a id="idp79155840" class="indexterm"></a><p>FreeBSD provides the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> Bourne script to aid
	in determining the differences between the configuration files
	in <code class="filename">/etc</code>, and the configuration files in
	<code class="filename">/usr/src/etc</code>.  This is the recommended
	solution for keeping the system configuration files up to date
	with those located in the source tree, as it uses a 3-way
	merge algorithm to compare the source tree used for the
	previous installworld and current installworld, and
	automatically merges any updates to the installed system
	without clobbering local changes which have been made to the
	system.</p><p>Note that <code class="command">etcupdate</code> has replaced
	<a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=mergemaster&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">mergemaster</span>(8)</span></a> as the recommended method to update
	configuration files, as the latter required the user to review
	all of the differences between the new source tree and the
	installed system, and manually select which changes should be
	applied, even if there had been no local changes made to the
	file from the previous source tree used to install it.</p><div class="sect3"><div xmlns="" class="titlepage"><div><div><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="etcupdate-bootstrap"></a>23.6.4.1. Bootstrapping <code class="command">etcupdate</code> (First time only)</h4></div></div></div><p>If you have not previously performed an install world
	  using the <code class="command">etcupdate</code> utility to perform
	  the post install merging of the configuration files, then
	  it will need to be bootstrapped.  This step essentially
	  involves providing <code class="command">etcupdate</code> with a copy
	  of the source tree that matches the
	  <span class="emphasis"><em>currently</em></span> installed world.</p><div xmlns="" class="important"><h3 class="admontitle">Important: </h3><p xmlns="http://www.w3.org/1999/xhtml">This is only required the first time that
	  <code class="command">etcupdate</code> is used to perform an install
	  world, as it saves a copy of the new world each time it is
	  used.</p></div><p>To check whether <code class="command">etcupdate</code>
	  already has a copy of the correct source tree, or if it
	  needs to be bootstrapped, confirm that the following command
	  shows only the local changes which have been made to the
	  system.  If it shows an unexpected result, or if it fails
	  with an error about a missing reference tree, then it is
	  likely that <code class="command">etcupdate</code> needs to be
	  bootstrapped.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate diff | less</code></strong></pre><p>To bootstrap <code class="command">etcupdate</code>, you must
	  first obtain a copy of the source tree which matches your
	  <span class="emphasis"><em>currently</em></span> installed world.  This is not
	  referring to the updated source tree which is about to to
	  be installed to the system, but a copy of the source tree
	  which matches the <span class="emphasis"><em>currently</em></span> running
	  system (used during the previous install or update).
	  If you are running a RELEASE branch, this must be a copy
	  of the source tree which includes all changes for
	  security/errata updates which have been installed (this
	  applies even if you have previously been performing binary
	  updates using the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=freebsd-update&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">freebsd-update</span>(8)</span></a> utility).</p><p>If you do not have a copy of the matching source tree
	  readily available, the easiest way to obtain it is to
	  download it using <span class="application">subversion</span>:
	</p><pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>svn checkout -r <em class="replaceable"><code>YOURREVISION</code></em> https://svn.FreeBSD.org/base/head/ <em class="replaceable"><code>/PATH/TO/SAVE/SOURCE/TREE</code></em></code></strong></pre><p>Once you have the source tree matching the current
	  world, use it to bootstrap <code class="command">etcupdate</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate extract -s <em class="replaceable"><code>/PATH/TO/SAVED/SOURCE/TREE</code></em></code></strong></pre></div><div class="sect3"><div xmlns="" class="titlepage"><div><div><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="etcupdate-merge"></a>23.6.4.2. Merging Configuration Files (Post installworld)</h4></div></div></div><p>Before using <code class="command">etcupdate</code>, it is
	  recommended to have a backup or snapshot of
	  <code class="filename">/etc</code>.  If using the
	  <code class="command">copy</code> command to take a local backup,
	  include <code class="option">-R</code> which does a recursive copy and
	  <code class="option">-p</code> which preserves times and the ownerships
	  on files:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cp -Rp /etc /etc.old</code></strong></pre><div xmlns="" class="warning"><h3 class="admontitle">Warning: </h3><p xmlns="http://www.w3.org/1999/xhtml"><code class="command">etcupdate</code> needs to be bootstrapped the
	    first time it is used to merge configuration files
	    post-<code class="buildtarget">installworld</code>.  See
	    <a class="xref" href="makeworld.html#etcupdate-bootstrap" title="23.6.4.1. Bootstrapping etcupdate (First time only)">Section 23.6.4.1, &#8220;Bootstrapping <code class="command">etcupdate</code> (First time only)&#8221;</a>.</p></div><p>When run in the default mode (with no further arguments),
	  <code class="command">etcupdate</code> first moves it's backup of the
	  old source tree from
	  <code class="filename">/var/db/etcupdate/current/</code> to the
	  <code class="filename">/var/db/etcupdate/previous/</code>, and then
	  takes a copy of the new source tree from
	  <code class="filename">/usr/src/</code> to
	  <code class="filename">/var/db/etcupdate/current/</code>.</p><p>Next, <code class="command">etcupdate</code> compares the files in
	  the "current" and "previous" trees, and performs a 3-way merge
	  to the installed system.  New files will be added, removed
	  files will be deleted, and modified files will be updated,
	  only if it it will not cobber any local changes.  If the merge
	  encounters conflicts, then a version of the offending file
	  will be saved with conflict markers for future resolution, and
	  <code class="command">etcupdate</code> will generate a warning.</p><p>For each file that is updated a line will be output with a
	  leading character to indicate the action taken:</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Leading character</th><th>Action taken</th></tr></thead><tbody><tr><td>A</td><td>Added</td></tr><tr><td>C</td><td>Conflict</td></tr><tr><td>D</td><td>Deleted</td></tr><tr><td>M</td><td>Merged</td></tr><tr><td>U</td><td>Updated</td></tr></tbody></table></div><p>Note that for certain files <code class="command">etcupdate</code>
	  will perform post-install actions any time they updated:</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Modified file</th><th>Post-install action</th></tr></thead><tbody><tr><td><code class="filename">/etc/master.passwd</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=pwd_mkdb&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">pwd_mkdb</span>(8)</span></a> is invoked</td></tr><tr><td><code class="filename">/etc/login.conf</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=cap_mkdb&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">cap_mkdb</span>(1)</span></a> is invoked to update <code class="filename">/etc/login.conf.db</code></td></tr><tr><td><code class="filename">/etc/mail/aliases</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=newaliases&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">newaliases</span>(1)</span></a> is invoked *</td></tr><tr><td><code class="filename">/etc/services</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=services.mkdb&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">services.mkdb</span>(8)</span></a> is invoked</td></tr><tr><td><code class="filename">/etc/localtime</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=tzsetup&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">tzsetup</span>(8)</span></a> is invoked if <code class="filename">/var/db/zoneinfo</code> exists</td></tr><tr><td><code class="filename">/etc/motd</code></td><td><code class="command">/etc/rc.d/motd</code> is invoked *</td></tr></tbody></table></div><p>* These post-install actions only occur if
	  <code class="command">etcupdate</code> is updating file directly to
	  <code class="filename">/etc/</code> (the default behaviour).  Refer to
	  the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> man page for behaviour if the
	  <code class="option">-D</code> option has been used to merge
	  configuration files in a non-default destination directory
	  (for example, when using boot environments).</p></div></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="make-delete-old"></a>23.6.5. Deleting Obsolete Files and Libraries</h3></div><div><span class="authorgroup">Based on notes provided by <span xmlns="http://www.w3.org/1999/xhtml" class="author"><span class="firstname">Anton</span> <span class="surname">Shterenlikht</span></span>. </span></div></div></div><a id="idp78639104" class="indexterm"></a><p>As a part of the FreeBSD 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
	<code class="filename">/usr/src/ObsoleteFiles.inc</code>.  The
	following instructions should be used to remove obsolete files
	during the system upgrade process.</p><p>After the <code class="command">make installworld</code> and the
	subsequent <code class="command">etcupdate</code> have finished
	successfully, check for obsolete files and libraries:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make check-old</code></strong></pre><p>If any obsolete files are found, they can be deleted using
	the following command:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make delete-old</code></strong></pre><p>A prompt is displayed before deleting each obsolete file.
	To skip the prompt and let the system remove these files
	automatically, use
	<code class="varname">BATCH_DELETE_OLD_FILES</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -DBATCH_DELETE_OLD_FILES delete-old</code></strong></pre><p>The same goal can be achieved by piping these commands
	through <code class="command">yes</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>yes|make delete-old</code></strong></pre><div xmlns="" class="warning"><h3 class="admontitle">Warning: </h3><p xmlns="http://www.w3.org/1999/xhtml">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 <code class="command">make delete-old-libs</code> is
	  executed.</p></div><p>Utilities for checking shared library dependencies include
	<a xmlns="" class="package" href="http://www.freebsd.org/cgi/url.cgi?ports/sysutils/libchk/pkg-descr">sysutils/libchk</a> and
	<a xmlns="" class="package" href="http://www.freebsd.org/cgi/url.cgi?ports/sysutils/bsdadminscripts/pkg-descr">sysutils/bsdadminscripts</a>.</p><p>Obsolete shared libraries can conflict with newer
	libraries, causing messages like these:</p><pre class="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</pre><p>To solve these problems, determine which port installed
	the library:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkg which /usr/local/lib/libtiff.so</code></strong>
  /usr/local/lib/libtiff.so was installed by package tiff-3.9.4
<code class="prompt">#</code> <strong class="userinput"><code>pkg which /usr/local/lib/libXext.so</code></strong>
  /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</pre><p>Then deinstall, rebuild, and reinstall the port.  To
	automate this process,
	<a xmlns="" class="package" href="http://www.freebsd.org/cgi/url.cgi?ports/ports-mgmt/portmaster/pkg-descr">ports-mgmt/portmaster</a> can be used.  After
	all ports are rebuilt and no longer use the old libraries,
	delete the old libraries using the following command:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make delete-old-libs</code></strong></pre><p>If something goes wrong, it is easy to rebuild a
	particular piece of the system.  For example, if
	<code class="filename">/etc/magic</code> was accidentally deleted as
	part of the upgrade or merge of <code class="filename">/etc</code>,
	<code class="command">file</code> will stop working.  To fix this,
	run:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src/usr.bin/file</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make all install</code></strong></pre></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="updating-questions"></a>23.6.6. Common Questions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">Do I need to re-make the world for every
	      change?</span></dt><dd><p>It depends upon the nature of the change.  For
	      example, if <span class="application">svn</span> only shows
	      the following files as being updated:</p><pre class="screen"><code class="filename">src/games/cribbage/instr.c</code>
<code class="filename">src/games/sail/pl_main.c</code>
<code class="filename">src/release/sysinstall/config.c</code>
<code class="filename">src/release/sysinstall/media.c</code>
<code class="filename">src/share/mk/bsd.port.mk</code></pre><p>it probably is not worth rebuilding the entire
	      world.  Instead, go into the appropriate sub-directories
	      and run <code class="command">make all install</code>.  But if
	      something major changes, such as
	      <code class="filename">src/lib/libc/stdlib</code>, consider
	      rebuilding world.</p><p>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 FreeBSD-STABLE or FreeBSD-CURRENT.</p></dd><dt><span class="term">What would cause a compile to fail with lots of
	    signal 11<a id="idp79239296" class="indexterm"></a>
	    (or other signal number) errors?</span></dt><dd><p>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 <span class="application">make</span>
	      is restarted and it dies at a different point in the
	      process.</p><p>To resolve this error, swap out the components in
	      the machine, starting with RAM, to determine which
	      component is failing.</p></dd><dt><span class="term">Can <code class="filename">/usr/obj</code>
	      be removed when finished?</span></dt><dd><p>This directory contains all the object files that
	      were produced during the compilation phase.  Normally,
	      one of the first steps in the <code class="command">make
		buildworld</code> process is to remove this
	      directory and start afresh.  Keeping
	      <code class="filename">/usr/obj</code> around when finished makes
	      little sense, and its removal frees up a approximately
	      2GB of disk space.</p></dd><dt><span class="term">Can interrupted builds be resumed?</span></dt><dd><p>This depends on how far into the process the
	      problem occurs.  In general, <code class="command">make
		buildworld</code> 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.</p><p>During the last stage, it is fairly safe to run
	      these commands as they will not undo the work of the
	      previous <code class="command">make buildworld</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make -DNO_CLEAN all</code></strong></pre><p>If this message appears:</p><pre class="screen">--------------------------------------------------------------
Building everything..
--------------------------------------------------------------</pre><p>in the <code class="command">make buildworld</code> output,
	      it is probably fairly safe to do so.</p><p>If that message is not displayed, it is always
	      better to be safe than sorry and to restart the build
	      from scratch.</p></dd><dt><span class="term">Is it possible to speed up making the world?</span></dt><dd><p>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.</p><p>Careful file system design or the use of ZFS
	      datasets can make a difference.  Consider putting
	      <code class="filename">/usr/src</code> and
	      <code class="filename">/usr/obj</code> on
	      separate file systems.  If possible, place the file
	      systems on separate disks on separate disk controllers.
	      When mounting <code class="filename">/usr/src</code>, use
	      <code class="option">noatime</code> which prevents the file system
	      from recording the file access time.  If <code class="filename">/usr/src</code> is not on its
	      own file system, consider remounting <code class="filename">/usr</code> with
	      <code class="option">noatime</code>.</p><p>The file system holding <code class="filename">/usr/obj</code> can be mounted
	      or remounted with <code class="option">async</code> 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.</p><div xmlns="" class="warning"><h3 class="admontitle">Warning: </h3><p xmlns="http://www.w3.org/1999/xhtml">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.</p><p xmlns="http://www.w3.org/1999/xhtml">If <code class="filename">/usr/obj</code> 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.</p></div><p>Turn off profiling by setting
	      <span class="quote">&#8220;<span class="quote">NO_PROFILE=true</span>&#8221;</span> in
	      <code class="filename">/etc/make.conf</code>.</p><p>Pass <code class="option">-j<em class="replaceable"><code>n</code></em></code>
	      to <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=make&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> to run multiple processes in parallel.
	      This usually helps on both single- and multi-processor
	      machines.</p></dd><dt><span class="term">What if something goes wrong?</span></dt><dd><p>First, make absolutely sure that the environment has
	      no extraneous cruft from earlier builds:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>chflags -R noschg /usr/obj/usr</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>rm -rf /usr/obj/usr</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make cleandir</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make cleandir</code></strong></pre><p>Yes, <code class="command">make cleandir</code> really should
	      be run twice.</p><p>Then, restart the whole process, starting with
	      <code class="command">make buildworld</code>.</p><p>If problems persist, send the error and the output
	      of <code class="command">uname -a</code> to <a class="link" href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions" target="_top">FreeBSD general questions mailing list</a>.  Be
	      prepared to answer other questions about the
	      setup!</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="synching.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="updating-upgrading.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="small-lan.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">23.5. Synchronizing Source </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 23.7. Tracking for Multiple Machines</td></tr></table></div><p xmlns="" align="center"><small>All FreeBSD documents are available for download
    at <a href="http://ftp.FreeBSD.org/pub/FreeBSD/doc/">http://ftp.FreeBSD.org/pub/FreeBSD/doc/</a></small></p><p xmlns="" align="center"><small>Questions that are not answered by the
    <a href="http://www.FreeBSD.org/docs.html">documentation</a> may be
    sent to &lt;<a href="mailto:freebsd-questions@FreeBSD.org">freebsd-questions@FreeBSD.org</a>&gt;.<br />
    Send questions about this document to &lt;<a href="mailto:freebsd-doc@FreeBSD.org">freebsd-doc@FreeBSD.org</a>&gt;.</small></p></body></html>

Attachment #166719
Patch to update handbook to replace mergemaster(8) with etcupdate(8)	patch	2016-02-07 21:29:45 UTC	23.99 KB	no flags	Details

Attachment #166720
QA: Successully built makeworld.html section from handbook (with proposed changes)	text/html	2016-02-07 21:31:30 UTC	52.96 KB	no flags	Details

<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /><title>23.6. Rebuilding World</title><link rel="stylesheet" type="text/css" href="docbook.css" /><link rev="made" href="mailto:doc@FreeBSD.org" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="FreeBSD Handbook" /><link rel="up" href="updating-upgrading.html" title="Chapter 23. Updating and Upgrading FreeBSD" /><link rel="prev" href="synching.html" title="23.5. Synchronizing Source" /><link rel="next" href="small-lan.html" title="23.7. Tracking for Multiple Machines" /><link rel="copyright" href="legalnotice.html" title="Copyright" /><script xmlns="" type="text/javascript" src="/layout/js/google.js"></script></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">23.6. Rebuilding World</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="synching.html">Prev</a> </td><th width="60%" align="center">Chapter 23. Updating and Upgrading FreeBSD</th><td width="20%" align="right"> <a accesskey="n" href="small-lan.html">Next</a></td></tr></table><hr /></div><div class="sect1"><div xmlns="" class="titlepage"><div><div><h2 xmlns="http://www.w3.org/1999/xhtml" class="title" style="clear: both"><a id="makeworld"></a>23.6. Rebuilding World</h2></div></div></div><a id="idp78990464" class="indexterm"></a><p>Once the local source tree is synchronized against a
      particular version of FreeBSD such as FreeBSD-STABLE or FreeBSD-CURRENT,
      the source tree can be used to rebuild the system.  This process
      is known as rebuilding world.</p><p><span class="emphasis"><em>Before</em></span> rebuilding world, be sure to
      perform the following tasks:</p><div class="procedure"><a id="idp78992512"></a><div class="procedure-title">Procedure 23.1. Perform These Tasks <span class="emphasis"><em>Before</em></span>
	Building World</div><ol class="procedure" type="1"><li class="step"><p>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
	  <span class="emphasis"><em>before</em></span> 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!</p></li><li class="step"><a id="idp78994944" class="indexterm"></a><p>Review the recent <a class="link" href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-stable" target="_top">freebsd-stable</a> or <a class="link" href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-current" target="_top">freebsd-current</a>
	  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 <span class="quote">&#8220;<span class="quote">all clear</span>&#8221;</span> 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.</p></li><li class="step"><p>If you have not previously performed an 
	  <code class="buildtarget">installworld</code> using the
	  <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> utility to perform the merging of the
	  configuration files in <code class="filename">/etc/</code>, then it
	  will need to be bootstrapped.  For details on how to perform
	  the bootstrapping procedure, or how to determine whether it
	  is required, see <a class="xref" href="makeworld.html#etcupdate-bootstrap" title="23.6.4.1. Bootstrapping etcupdate (First time only)">Section 23.6.4.1, &#8220;Bootstrapping <code class="command">etcupdate</code> (First time only)&#8221;</a>.
	</p></li><li class="step"><p>Read <code class="filename">/usr/src/UPDATING</code> 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 <code class="filename">UPDATING</code> contradicts
	  any steps in this chapter, the instructions in
	  <code class="filename">UPDATING</code> take precedence and should be
	  followed.</p></li></ol></div><div xmlns="" class="warning"><h3 class="admontitle">Do Not Use <code xmlns="http://www.w3.org/1999/xhtml" class="command">make world</code>: </h3><p xmlns="http://www.w3.org/1999/xhtml">Some older documentation recommends using <code class="command">make
	  world</code>.  However, that command skips some important
	steps and should only be used by experts.  For almost all
	circumstances <code class="command">make world</code> is the wrong thing
	to do, and the procedure described here should be used
	instead.</p></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="canonical-build"></a>23.6.1. Overview of Process</h3></div></div></div><p>The build world process assumes an upgrade from an older
	FreeBSD version using the source of a newer version that was
	obtained using the instructions in <a class="xref" href="synching.html" title="23.5. Synchronizing Source">Section 23.5, &#8220;Synchronizing Source&#8221;</a>.</p><p>In FreeBSD, the term <span class="quote">&#8220;<span class="quote">world</span>&#8221;</span> 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.</p><p>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.</p><p>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.</p><p>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, <code class="filename">/usr/src/UPDATING</code> will
	indicate if any files need to be manually deleted and at which
	step to do so.</p><p>These concerns have led to the recommended upgrade
	sequence described in the following procedure.</p><div xmlns="" class="note"><h3 class="admontitle">Note: </h3><p xmlns="http://www.w3.org/1999/xhtml">It is a good idea to save the output from running
	  <code class="command">make</code> to a file.  If something goes wrong,
	  a copy of the error message can be posted to one of the FreeBSD
	  mailing lists.</p><p xmlns="http://www.w3.org/1999/xhtml">The easiest way to do this is to use
	  <code class="command">script</code> with a parameter that specifies
	  the name of the file to save all output to.  Do not save the
	  output to <code class="filename">/tmp</code> as this directory may be
	  cleared at next reboot.  A better place to save the file is
	  <code class="filename">/var/tmp</code>.  Run this command immediately
	  before rebuilding the world, and then type
	  <strong class="userinput"><code>exit</code></strong> when the process has
	  finished:</p><pre xmlns="http://www.w3.org/1999/xhtml" class="screen"><code class="prompt">#</code> <strong class="userinput"><code>script <em class="replaceable"><code>/var/tmp/mw.out</code></em></code></strong>
Script started, output file is /var/tmp/mw.out</pre></div><div class="procedure"><a id="idp79017216"></a><div class="procedure-title">Procedure 23.2. Overview of Build World Process</div><p>The commands used in the build world process should be
	  run in the order specified here.  This section summarizes
	  the function of each command.</p><ol class="procedure" type="1"><li class="step"><p>If the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> utility has not previously
	    been used during an update to perform the merging of the
	    configuration files in <code class="filename">/etc/</code>, then it
	    will need to be bootstrapped using a copy of the FreeBSD
	    source tree which matches the <span class="emphasis"><em>currently</em></span>
	    installed system (pre-update):</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate extract -s <em class="replaceable"><code>/PATH/TO/PREVIOUS/SOURCE/TREE</code></em></code></strong></pre></li><li class="step"><p>If the build world process has previously been run on
	    this system, a copy of the previous build may still exist
	    in <code class="filename">/usr/obj</code>.  To
	    speed up the new build world process, and possibly save
	    some dependency headaches, remove this directory if it
	    already exists:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>chflags -R noschg /usr/obj/*</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>rm -rf /usr/obj</code></strong></pre></li><li class="step"><p>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 <code class="filename">/usr/obj</code>.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make buildworld</code></strong></pre></li><li class="step"><p>Use the new compiler residing in <code class="filename">/usr/obj</code> 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
	    <code class="command">ps</code> and <code class="command">top</code> will fail
	    to work if the kernel and source code versions are not the
	    same.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make buildkernel</code></strong></pre></li><li class="step"><p>Install the new kernel and kernel modules, making it
	    possible to boot with the newly updated kernel.  If
	    <code class="varname">kern.securelevel</code> has been raised above
	    <code class="literal">1</code> <span class="emphasis"><em>and</em></span>
	    <code class="literal">noschg</code> 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 <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=init&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">init</span>(8)</span></a> for
	    details about <code class="varname">kern.securelevel</code> and
	    <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=chflags&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">chflags</span>(1)</span></a> for details about the various file
	    flags.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make installkernel</code></strong></pre></li><li class="step"><p>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.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>shutdown now</code></strong></pre><p>Once in single-user mode, run these commands if the
	    system is formatted with UFS:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>mount -u /</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>mount -a -t ufs</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>swapon -a</code></strong></pre><p>If the system is instead formatted with ZFS, run these
	    two commands.  This example assumes a zpool name of
	    <code class="literal">zroot</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>zfs set readonly=off zroot</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>zfs mount -a</code></strong></pre></li><li class="step"><p>Optional: If a keyboard mapping other than the default
	    US English is desired, it can be changed with
	    <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=kbdmap&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">kbdmap</span>(1)</span></a>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>kbdmap</code></strong></pre></li><li class="step"><p>Then, for either file system, if the
	    <acronym class="acronym">CMOS</acronym> clock is set to local time (this
	    is true if the output of <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=date&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">date</span>(1)</span></a> does not show the
	    correct time and zone), run:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>adjkerntz -i</code></strong></pre></li><li class="step"><p>Remaking the world will not update certain
	    directories, such as <code class="filename">/etc/</code>,
	    <code class="filename">/var/</code> and <code class="filename">/usr/</code>,
	    with new or changed configuration files.  The next step is
	    to perform some initial configuration file updates
	    to <code class="filename">/etc/</code> in preparation for the new
	    world.  Use the <code class="option">-n</code> option to first perform a
	    "dry-run", which will report what actions would be taken,
	    but will not actually make any changes.  Refer to
	    <a class="xref" href="makeworld.html#etcupdate" title="23.6.4. Merging Configuration Files">Section 23.6.4, &#8220;Merging Configuration Files&#8221;</a> for more details about this
	    command:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate -pn | less</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>etcupdate -p</code></strong></pre></li><li class="step"><p>Install the new world and system binaries from
	    <code class="filename">/usr/obj</code>.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make installworld</code></strong></pre></li><li class="step"><p>Update any remaining configuration files.
	    Use the <code class="option">-n</code> option to first perform a
	    "dry-run", which will report what actions would be taken,
	    but will not actually make any changes.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate -n | less</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>etcupdate</code></strong></pre></li><li class="step"><p>Delete any obsolete files.  This is important as they
	    may cause problems if left on the disk.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make delete-old</code></strong></pre></li><li class="step"><p>A full reboot is now needed to load the new kernel and
	    new world with the new configuration files.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>reboot</code></strong></pre></li><li class="step"><p>Make sure that all installed ports have first been
	    rebuilt before old libraries are removed using the
	    instructions in  <a class="xref" href="ports-using.html#ports-upgrading" title="4.5.3. Upgrading Ports">Section 4.5.3, &#8220;Upgrading Ports&#8221;</a>.  When
	    finished, remove any obsolete libraries to avoid conflicts
	    with newer ones.  For a more detailed description of this
	    step, refer to <a class="xref" href="makeworld.html#make-delete-old" title="23.6.5. Deleting Obsolete Files and Libraries">Section 23.6.5, &#8220;Deleting Obsolete Files and Libraries&#8221;</a>.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make delete-old-libs</code></strong></pre></li></ol></div><a id="idp79072384" class="indexterm"></a><p>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.</p></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="src-updating"></a>23.6.2. Configuration Files</h3></div></div></div><a id="idp79074176" class="indexterm"></a><p>This build world process uses several configuration
	files.</p><p>The <code class="filename">Makefile</code> located in
	<code class="filename">/usr/src</code> describes how the programs that
	comprise FreeBSD should be built and the order in which they
	should be built.</p><p>The options available to <code class="command">make</code> are
	described in <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=make.conf&amp;sektion=5"><span class="citerefentry"><span class="refentrytitle">make.conf</span>(5)</span></a> and some common examples are
	included in
	<code class="filename">/usr/share/examples/etc/make.conf</code>.  Any
	options which are added to <code class="filename">/etc/make.conf</code>
	will control the how <code class="command">make</code> runs and builds
	programs.  These options take effect every time
	<code class="command">make</code> is used, including compiling
	applications from the Ports Collection, compiling custom C
	programs, or building the FreeBSD 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.</p><a id="idp79092096" class="indexterm"></a><p>How the operating system is built from source code is
	controlled by <code class="filename">/etc/src.conf</code>.  Unlike
	<code class="filename">/etc/make.conf</code>, the contents of
	<code class="filename">/etc/src.conf</code> only take effect when the
	FreeBSD operating system itself is being built.  Descriptions of
	the many options available for this file are shown in
	<a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=src.conf&amp;sektion=5"><span class="citerefentry"><span class="refentrytitle">src.conf</span>(5)</span></a>.  Be cautious about disabling seemingly
	unneeded kernel modules and build options.  Sometimes there
	are unexpected or subtle interactions.</p></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="make-buildworld"></a>23.6.3. Variables and Targets</h3></div></div></div><p>The general format for using <code class="command">make</code> is as
	follows:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -<em class="replaceable"><code>x</code></em> -D<em class="replaceable"><code>VARIABLE</code></em> <em class="replaceable"><code>target</code></em></code></strong></pre><p>In this example,
	<code class="option">-<em class="replaceable"><code>x</code></em></code> is an option
	passed to <code class="command">make</code>.  Refer to <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=make&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> for
	examples of the available options.</p><p>To pass a variable, specify the variable name with
	<code class="option">-D<em class="replaceable"><code>VARIABLE</code></em></code>.  The
	behavior of the <code class="filename">Makefile</code> is controlled by
	variables.  These can either be set in
	<code class="filename">/etc/make.conf</code> or they can be specified
	when using <code class="command">make</code>.  For example, this
	variable specifies that profiled libraries should not be
	built:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -DNO_PROFILE <em class="replaceable"><code>target</code></em></code></strong></pre><p>It corresponds with this setting in
	<code class="filename">/etc/make.conf</code>:</p><pre class="programlisting">NO_PROFILE=    true     #    Avoid compiling profiled libraries</pre><p>The <em class="replaceable"><code>target</code></em> tells
	<code class="command">make</code> what to do and the
	<code class="filename">Makefile</code> 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.</p><p>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,
	<code class="buildtarget">buildworld</code> can be safely run on a
	machine running in multi-user mode.  It is still recommended
	that <code class="buildtarget">installworld</code> be run in part in
	single-user mode, though.</p><p>Secondly, it allows <acronym class="acronym">NFS</acronym> mounts to be
	used to upgrade multiple machines on a network, as described
	in <a class="xref" href="small-lan.html" title="23.7. Tracking for Multiple Machines">Section 23.7, &#8220;Tracking for Multiple Machines&#8221;</a>.</p><p>It is possible to specify <code class="option">-j</code> which will
	cause <code class="command">make</code> to spawn several simultaneous
	processes.  Since much of the compiling process is
	<acronym class="acronym">I/O</acronym>-bound rather than
	<acronym class="acronym">CPU</acronym>-bound, this is useful on both single
	<acronym class="acronym">CPU</acronym> and multi-<acronym class="acronym">CPU</acronym>
	machines.</p><p>On a single-<acronym class="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.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -j4 buildworld</code></strong></pre><p>On a multi-<acronym class="acronym">CPU</acronym> machine, try values
	between <code class="literal">6</code> and <code class="literal">10</code> to see
	how they speed things up.</p><a id="idp79123456" class="indexterm"></a><div xmlns="" class="note"><h3 class="admontitle">Note: </h3><p xmlns="http://www.w3.org/1999/xhtml">If any variables were specified to <code class="command">make
	    buildworld</code>, specify the same variables to
	  <code class="command">make installworld</code>.  However,
	  <code class="option">-j</code> must <span class="emphasis"><em>never</em></span> be used
	  with <code class="buildtarget">installworld</code>.</p><p xmlns="http://www.w3.org/1999/xhtml">For example, if this command was used:</p><pre xmlns="http://www.w3.org/1999/xhtml" class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -DNO_PROFILE buildworld</code></strong></pre><p xmlns="http://www.w3.org/1999/xhtml">Install the results with:</p><pre xmlns="http://www.w3.org/1999/xhtml" class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -DNO_PROFILE installworld</code></strong></pre><p xmlns="http://www.w3.org/1999/xhtml">Otherwise, the second command will try to install
	  profiled libraries that were not built during the
	  <code class="command">make buildworld</code> phase.</p></div></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="etcupdate"></a>23.6.4. Merging Configuration Files</h3></div><div><span class="authorgroup">Originally written to describe the mergemaster(8) utility by <span xmlns="http://www.w3.org/1999/xhtml" class="author"><span class="firstname">Tom</span> <span class="surname">Rhodes</span></span>. </span></div><div><span class="authorgroup">Modified to describe the etcupdate(8) utility by <span xmlns="http://www.w3.org/1999/xhtml" class="author"><span class="firstname">Ben</span> <span class="surname">Woods</span></span>. </span></div></div></div><a id="idp79137024" class="indexterm"></a><p>FreeBSD provides the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> Bourne script to aid
	in determining the differences between the configuration files
	in <code class="filename">/etc/</code>, and the configuration files in
	<code class="filename">/usr/src/etc/</code>.  This is the recommended
	solution for keeping the system configuration files up to date
	with those located in the source tree, as it uses a 3-way
	merge algorithm to compare the source tree used for the
	previous installworld and current installworld, and
	automatically merges any updates to the installed system
	without clobbering local changes which have been made to the
	system.</p><div class="sect3"><div xmlns="" class="titlepage"><div><div><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="etcupdate-bootstrap"></a>23.6.4.1. Bootstrapping <code class="command">etcupdate</code> (First time only)</h4></div></div></div><p>If you have not previously performed an <code class="buildtarget">installworld</code>
	  using the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> utility to perform the merging
	  of the configuration files in <code class="filename">/etc/</code>,
	  then it will need to be bootstrapped.  This step essentially
	  involves providing <code class="command">etcupdate</code> with a copy
	  of the source tree that matches the
	  <span class="emphasis"><em>currently</em></span> installed world.</p><div xmlns="" class="important"><h3 class="admontitle">Important: </h3><p xmlns="http://www.w3.org/1999/xhtml">This is only required the first time that
	  <code class="command">etcupdate</code> is used to perform an install
	  world, as it saves a copy of the new world each time it is
	  used.</p></div><p>To check whether <code class="command">etcupdate</code>
	  already has a copy of the correct source tree, or if it
	  needs to be bootstrapped, confirm that the following command
	  shows only the local changes which have been made to the
	  system.  Files that differ from their originally installed
	  state  will be shown in <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=diff&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">diff</span>(1)</span></a> format, with the
	  <code class="option">+</code> sign representing added or modified
	  lines, and <code class="option">-</code> representing lines that will
	  be either removed completely or replaced with a new file.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate diff | less</code></strong></pre><p>If this command fails with an error about a missing
	  reference tree, then <code class="command">etcupdate</code> needs to
	  be bootstrapped.  If the output shows more changes than
	  expected, it is likely that <code class="command">etcupdate</code>
	  has either been bootstrapped from a source tree that doesn't
	  match the running system or was not run after the last
	  system update.  In either scenario, the solution is to
	  repeat the bootstrap process.</p><p>To bootstrap <code class="command">etcupdate</code>, you must
	  first obtain a copy of the source tree which matches your
	  <span class="emphasis"><em>currently</em></span> installed world.  This is not
	  referring to the updated source tree which is about to to
	  be installed to the system, but a copy of the source tree
	  which matches the <span class="emphasis"><em>currently</em></span> running
	  system (used during the previous install or update).
	  If you are running a <code class="literal">RELEASE</code> branch,
	  this must be a copy of the source tree which includes all
	  changes for security/errata updates which have been
	  installed (this applies even if you have previously been
	  performing binary updates using the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=freebsd-update&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">freebsd-update</span>(8)</span></a>
	  utility).</p><p>If you already have a copy of the FreeBSD source tree which
	  was checked-out using <span class="application">subversion</span>,
	  but it does not match the <span class="emphasis"><em>currently</em></span>
	  running system, it is possible to roll the tree back to the
	  matching version:</p><pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>uname -v</code></strong>
FreeBSD <em class="replaceable"><code>YOURRELEASE</code></em> #0 <em class="replaceable"><code>YOURREVISION</code></em>: <em class="replaceable"><code>BUILDTIMESTAMP</code></em>     <em class="replaceable"><code>BUILDUSER@BUILDHOST:/PATH/TO/KERNCONF</code></em>
<code class="prompt">%</code> <strong class="userinput"><code>svn update -r <em class="replaceable"><code>YOURREVISION</code></em></code></strong></pre><p>If you do not have a copy of the matching source tree
	  readily available, or have already updated it to a newer
	  version and do not want to roll it back, the easiest way to
	  obtain a new copy of the matching tree is to download it
	  using <span class="application">subversion</span>.  Here,
	  <em class="replaceable"><code>BRANCH</code></em> will typically be one of
	  <code class="literal">head</code>, <code class="literal">stable/<em class="replaceable"><code>MAJORVERSION</code></em></code> or
	  <code class="literal">releng/<em class="replaceable"><code>MAJORVERSION</code></em>.<em class="replaceable"><code>MINORVERSION</code></em></code>
	  (as listed at <a class="link" href="../../../../releng/" target="_top">www.freebsd.org/releng</a>):
	</p><pre class="screen"><code class="prompt">%</code> <strong class="userinput"><code>svn checkout -r <em class="replaceable"><code>YOURREVISION</code></em> svn://svn.FreeBSD.org/base/<em class="replaceable"><code>BRANCH</code></em>/ <em class="replaceable"><code>/PATH/TO/SAVE/SOURCE/TREE</code></em></code></strong></pre><p>Once you have the source tree matching the current
	  world, use it to bootstrap <code class="command">etcupdate</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate extract -s <em class="replaceable"><code>/PATH/TO/SAVED/SOURCE/TREE</code></em></code></strong></pre></div><div class="sect3"><div xmlns="" class="titlepage"><div><div><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="etcupdate-merge"></a>23.6.4.2. Merging Configuration Files</h4></div></div></div><div xmlns="" class="warning"><h3 class="admontitle">Warning: </h3><p xmlns="http://www.w3.org/1999/xhtml"><code class="command">etcupdate</code> needs to be bootstrapped the
	    first time it is used to merge configuration files
	    during an update.  See <a class="xref" href="makeworld.html#etcupdate-bootstrap" title="23.6.4.1. Bootstrapping etcupdate (First time only)">Section 23.6.4.1, &#8220;Bootstrapping <code class="command">etcupdate</code> (First time only)&#8221;</a>.</p></div><p><code class="command">etcupdate</code> should typically be run
	  twice in the update process. The first time should be
	  immediately before <code class="buildtarget">installworld</code>
	  with the <code class="option">-p</code> option, which updates only
	  those files that are essential for the success of
	  <code class="buildtarget">installworld</code>.
	  For instance, this step may add new groups, system accounts,
	  or startup scripts which have been added to FreeBSD since the
	  last update.  This is necessary so that the <code class="buildtarget">installworld</code>
	  step will be able to use any new system accounts, groups,
	  and scripts.  The second time should be immediately after
	  <code class="buildtarget">installworld</code> and without the
	  <code class="option">-p</code> option, to update the remainder of the
	  configuration files.</p><p>Each time the <code class="command">etcupdate</code> utility is
	  used, it is recommended to first perform a "dry-run" using
	  the <code class="option">-n</code> option.  This will report what
	  actions would be taken, but will not actually make any
	  changes.</p><p>When <code class="command">etcupdate</code> is run after
	  <code class="buildtarget">installworld</code> (with no further
	  arguments), it first moves it's backup of the old source
	  tree from <code class="filename">/var/db/etcupdate/current/</code> to
	  <code class="filename">/var/db/etcupdate/previous/</code>, and then
	  takes a copy of the new source tree from
	  <code class="filename">/usr/src/</code> to
	  <code class="filename">/var/db/etcupdate/current/</code>.
	  Next, <code class="command">etcupdate</code> compares the files in
	  the "current" and "previous" trees, and performs a 3-way merge
	  to the installed system.  New files will be added, removed
	  files will be deleted, and modified files will be updated,
	  only if it it will not cobber any local changes.  If the merge
	  encounters conflicts, then a version of the offending file
	  will be saved with conflict markers for future resolution, and
	  <code class="command">etcupdate</code> will generate a warning.</p><p>For each file that is updated a line will be output with a
	  leading character to indicate the action taken:</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Leading character</th><th>Action taken</th></tr></thead><tbody><tr><td>A</td><td>Added</td></tr><tr><td>C</td><td>Conflict</td></tr><tr><td>D</td><td>Deleted</td></tr><tr><td>M</td><td>Merged</td></tr><tr><td>U</td><td>Updated</td></tr></tbody></table></div><p>Note that for certain files, <code class="command">etcupdate</code>
	  will automatically perform post-install actions any time
	  they are updated:</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Modified file</th><th>Post-install action</th></tr></thead><tbody><tr><td><code class="filename">/etc/master.passwd</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=pwd_mkdb&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">pwd_mkdb</span>(8)</span></a> is invoked</td></tr><tr><td><code class="filename">/etc/login.conf</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=cap_mkdb&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">cap_mkdb</span>(1)</span></a> is invoked to update <code class="filename">/etc/login.conf.db</code></td></tr><tr><td><code class="filename">/etc/mail/aliases</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=newaliases&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">newaliases</span>(1)</span></a> is invoked *</td></tr><tr><td><code class="filename">/etc/services</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=services.mkdb&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">services.mkdb</span>(8)</span></a> is invoked</td></tr><tr><td><code class="filename">/etc/localtime</code></td><td><a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=tzsetup&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">tzsetup</span>(8)</span></a> is invoked if <code class="filename">/var/db/zoneinfo</code> exists</td></tr><tr><td><code class="filename">/etc/motd</code></td><td><code class="command">/etc/rc.d/motd</code> is invoked *</td></tr></tbody></table></div><p>* These post-install actions only occur if
	  <code class="command">etcupdate</code> is updating file directly to
	  <code class="filename">/etc/</code> (the default behaviour).  Refer to
	  the <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=etcupdate&amp;sektion=8"><span class="citerefentry"><span class="refentrytitle">etcupdate</span>(8)</span></a> man page for behaviour if the
	  <code class="option">-D</code> option has been used to merge
	  configuration files in a non-default destination directory
	  (for example, when using boot environments).</p></div><div class="sect3"><div xmlns="" class="titlepage"><div><div><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="etcupdate-resolve"></a>23.6.4.3. Resolving Conflicts After Merging Configuration Files</h4></div></div></div><p>If <code class="command">etcupdate</code> has reported any
	  conflicts when updating the configuration files, it must be
	  run once more in "resolve" mode.</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>etcupdate resolve</code></strong></pre><p>In this mode, <code class="command">etcupdate</code> iterates over
	  any existing conflicts and prompts the user for actions to
	  take on each conflicted file.  For each file, the following
	  actions are available:</p><div class="informaltable"><table border="1"><colgroup><col /><col /></colgroup><thead><tr><th>Prompt</th><th>Action Description</th></tr></thead><tbody><tr><td>(p) postpone</td><td>Ignore this conflict for now.  It will remain for subsequent calls of <code class="command">etcupdate resolve</code>.</td></tr><tr><td>(df) diff-full</td><td>Show all changes made to the merged file as a unified <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=diff&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">diff</span>(1)</span></a>.</td></tr><tr><td>(e) edit</td><td>Manually edit the merged file in an editor.</td></tr><tr><td>(r) resolved</td><td>Install the manually edited version of the file into the destination directory.  Used after the (e) edit option.</td></tr><tr><td>(mf) mine-full</td><td>Use the version of the file in the running system and ignore any changes made to the file in the new source tree.</td></tr><tr><td>(tf) theirs-full</td><td>Use the version of the file from the new source tree and discard any local changes made to the file.</td></tr><tr><td>(h) help</td><td>Display the list of commands.</td></tr></tbody></table></div></div></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="make-delete-old"></a>23.6.5. Deleting Obsolete Files and Libraries</h3></div><div><span class="authorgroup">Based on notes provided by <span xmlns="http://www.w3.org/1999/xhtml" class="author"><span class="firstname">Anton</span> <span class="surname">Shterenlikht</span></span>. </span></div></div></div><a id="idp79253248" class="indexterm"></a><p>As a part of the FreeBSD 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
	<code class="filename">/usr/src/ObsoleteFiles.inc</code>.  The
	following instructions should be used to remove obsolete files
	during the system upgrade process.</p><p>After the <code class="command">make installworld</code> and the
	subsequent <code class="command">etcupdate</code> have finished
	successfully, check for obsolete files and libraries:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make check-old</code></strong></pre><p>If any obsolete files are found, they can be deleted using
	the following command:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make delete-old</code></strong></pre><p>A prompt is displayed before deleting each obsolete file.
	To skip the prompt and let the system remove these files
	automatically, use
	<code class="varname">BATCH_DELETE_OLD_FILES</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make -DBATCH_DELETE_OLD_FILES delete-old</code></strong></pre><p>The same goal can be achieved by piping these commands
	through <code class="command">yes</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>yes|make delete-old</code></strong></pre><div xmlns="" class="warning"><h3 class="admontitle">Warning: </h3><p xmlns="http://www.w3.org/1999/xhtml">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 <code class="command">make delete-old-libs</code> is
	  executed.</p></div><p>Utilities for checking shared library dependencies include
	<a xmlns="" class="package" href="http://www.freebsd.org/cgi/url.cgi?ports/sysutils/libchk/pkg-descr">sysutils/libchk</a> and
	<a xmlns="" class="package" href="http://www.freebsd.org/cgi/url.cgi?ports/sysutils/bsdadminscripts/pkg-descr">sysutils/bsdadminscripts</a>.</p><p>Obsolete shared libraries can conflict with newer
	libraries, causing messages like these:</p><pre class="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</pre><p>To solve these problems, determine which port installed
	the library:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>pkg which /usr/local/lib/libtiff.so</code></strong>
  /usr/local/lib/libtiff.so was installed by package tiff-3.9.4
<code class="prompt">#</code> <strong class="userinput"><code>pkg which /usr/local/lib/libXext.so</code></strong>
  /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</pre><p>Then deinstall, rebuild, and reinstall the port.  To
	automate this process,
	<a xmlns="" class="package" href="http://www.freebsd.org/cgi/url.cgi?ports/ports-mgmt/portmaster/pkg-descr">ports-mgmt/portmaster</a> can be used.  After
	all ports are rebuilt and no longer use the old libraries,
	delete the old libraries using the following command:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make delete-old-libs</code></strong></pre><p>If something goes wrong, it is easy to rebuild a
	particular piece of the system.  For example, if
	<code class="filename">/etc/magic</code> was accidentally deleted as
	part of the upgrade or merge of <code class="filename">/etc</code>,
	<code class="command">file</code> will stop working.  To fix this,
	run:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src/usr.bin/file</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make all install</code></strong></pre></div><div class="sect2"><div xmlns="" class="titlepage"><div><div><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="updating-questions"></a>23.6.6. Common Questions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">Do I need to re-make the world for every
	      change?</span></dt><dd><p>It depends upon the nature of the change.  For
	      example, if <span class="application">svn</span> only shows
	      the following files as being updated:</p><pre class="screen"><code class="filename">src/games/cribbage/instr.c</code>
<code class="filename">src/games/sail/pl_main.c</code>
<code class="filename">src/release/sysinstall/config.c</code>
<code class="filename">src/release/sysinstall/media.c</code>
<code class="filename">src/share/mk/bsd.port.mk</code></pre><p>it probably is not worth rebuilding the entire
	      world.  Instead, go into the appropriate sub-directories
	      and run <code class="command">make all install</code>.  But if
	      something major changes, such as
	      <code class="filename">src/lib/libc/stdlib</code>, consider
	      rebuilding world.</p><p>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 FreeBSD-STABLE or FreeBSD-CURRENT.</p></dd><dt><span class="term">What would cause a compile to fail with lots of
	    signal 11<a id="idp79280000" class="indexterm"></a>
	    (or other signal number) errors?</span></dt><dd><p>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 <span class="application">make</span>
	      is restarted and it dies at a different point in the
	      process.</p><p>To resolve this error, swap out the components in
	      the machine, starting with RAM, to determine which
	      component is failing.</p></dd><dt><span class="term">Can <code class="filename">/usr/obj</code>
	      be removed when finished?</span></dt><dd><p>This directory contains all the object files that
	      were produced during the compilation phase.  Normally,
	      one of the first steps in the <code class="command">make
		buildworld</code> process is to remove this
	      directory and start afresh.  Keeping
	      <code class="filename">/usr/obj</code> around when finished makes
	      little sense, and its removal frees up a approximately
	      2GB of disk space.</p></dd><dt><span class="term">Can interrupted builds be resumed?</span></dt><dd><p>This depends on how far into the process the
	      problem occurs.  In general, <code class="command">make
		buildworld</code> 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.</p><p>During the last stage, it is fairly safe to run
	      these commands as they will not undo the work of the
	      previous <code class="command">make buildworld</code>:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make -DNO_CLEAN all</code></strong></pre><p>If this message appears:</p><pre class="screen">--------------------------------------------------------------
Building everything..
--------------------------------------------------------------</pre><p>in the <code class="command">make buildworld</code> output,
	      it is probably fairly safe to do so.</p><p>If that message is not displayed, it is always
	      better to be safe than sorry and to restart the build
	      from scratch.</p></dd><dt><span class="term">Is it possible to speed up making the world?</span></dt><dd><p>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.</p><p>Careful file system design or the use of ZFS
	      datasets can make a difference.  Consider putting
	      <code class="filename">/usr/src</code> and
	      <code class="filename">/usr/obj</code> on
	      separate file systems.  If possible, place the file
	      systems on separate disks on separate disk controllers.
	      When mounting <code class="filename">/usr/src</code>, use
	      <code class="option">noatime</code> which prevents the file system
	      from recording the file access time.  If <code class="filename">/usr/src</code> is not on its
	      own file system, consider remounting <code class="filename">/usr</code> with
	      <code class="option">noatime</code>.</p><p>The file system holding <code class="filename">/usr/obj</code> can be mounted
	      or remounted with <code class="option">async</code> 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.</p><div xmlns="" class="warning"><h3 class="admontitle">Warning: </h3><p xmlns="http://www.w3.org/1999/xhtml">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.</p><p xmlns="http://www.w3.org/1999/xhtml">If <code class="filename">/usr/obj</code> 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.</p></div><p>Turn off profiling by setting
	      <span class="quote">&#8220;<span class="quote">NO_PROFILE=true</span>&#8221;</span> in
	      <code class="filename">/etc/make.conf</code>.</p><p>Pass <code class="option">-j<em class="replaceable"><code>n</code></em></code>
	      to <a class="citerefentry" href="http://www.FreeBSD.org/cgi/man.cgi?query=make&amp;sektion=1"><span class="citerefentry"><span class="refentrytitle">make</span>(1)</span></a> to run multiple processes in parallel.
	      This usually helps on both single- and multi-processor
	      machines.</p></dd><dt><span class="term">What if something goes wrong?</span></dt><dd><p>First, make absolutely sure that the environment has
	      no extraneous cruft from earlier builds:</p><pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>chflags -R noschg /usr/obj/usr</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>rm -rf /usr/obj/usr</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>cd /usr/src</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make cleandir</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>make cleandir</code></strong></pre><p>Yes, <code class="command">make cleandir</code> really should
	      be run twice.</p><p>Then, restart the whole process, starting with
	      <code class="command">make buildworld</code>.</p><p>If problems persist, send the error and the output
	      of <code class="command">uname -a</code> to <a class="link" href="http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions" target="_top">FreeBSD general questions mailing list</a>.  Be
	      prepared to answer other questions about the
	      setup!</p></dd></dl></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="synching.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="updating-upgrading.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="small-lan.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">23.5. Synchronizing Source </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 23.7. Tracking for Multiple Machines</td></tr></table></div><p xmlns="" align="center"><small>All FreeBSD documents are available for download
    at <a href="http://ftp.FreeBSD.org/pub/FreeBSD/doc/">http://ftp.FreeBSD.org/pub/FreeBSD/doc/</a></small></p><p xmlns="" align="center"><small>Questions that are not answered by the
    <a href="http://www.FreeBSD.org/docs.html">documentation</a> may be
    sent to &lt;<a href="mailto:freebsd-questions@FreeBSD.org">freebsd-questions@FreeBSD.org</a>&gt;.<br />
    Send questions about this document to &lt;<a href="mailto:freebsd-doc@FreeBSD.org">freebsd-doc@FreeBSD.org</a>&gt;.</small></p></body></html>