<?xml version="1.0" encoding="iso-8859-1"?>
<!--
The FreeBSD Documentation Project
$FreeBSD$
-->
<chapter id="updating-upgrading">
<chapterinfo>
<authorgroup>
<author>
<firstname>Jim</firstname>
<surname>Mock</surname>
<contrib>Restructured, reorganized, and parts updated
by </contrib>
</author>
<!-- Mar 2000 -->
</authorgroup>
<authorgroup>
<author>
<firstname>Jordan</firstname>
<surname>Hubbard</surname>
<contrib>Original work by </contrib>
</author>
<author>
<firstname>Poul-Henning</firstname>
<surname>Kamp</surname>
</author>
<author>
<firstname>John</firstname>
<surname>Polstra</surname>
</author>
<author>
<firstname>Nik</firstname>
<surname>Clayton</surname>
</author>
</authorgroup>
<!-- with feedback from various others -->
</chapterinfo>
<title>Updating and Upgrading &os;</title>
<sect1 id="updating-upgrading-synopsis">
<title>Synopsis</title>
<para>&os; is under constant development between releases. Some
people prefer to use the officially released versions, while
others prefer to keep in sync with the latest developments.
However, even official releases are often updated with security
and other critical fixes. Regardless of the version used, &os;
provides all necessary tools to keep your system updated, and
also allows for easy upgrades between versions. This chapter
will help you decide if you want to track the development
system, or stick with one of the released versions. The basic
tools for keeping your system up to date are also
presented.</para>
<para>After reading this chapter, you will know:</para>
<itemizedlist>
<listitem>
<para>What utilities may be used to update the system and
the Ports Collection.</para>
</listitem>
<listitem>
<para>How to keep your system up to date with
<application>freebsd-update</application>,
<application>Subversion</application>, or
<application>CTM</application>.</para>
</listitem>
<listitem>
<para>How to compare the state of an installed system against
a known pristine copy.</para>
</listitem>
<listitem>
<para>How to keep your documentation up to date with
<application>Subversion</application> or documentation
ports<!--, and <application>Docsnap</application>-->.</para>
</listitem>
<listitem>
<para>The difference between the two development
branches: &os.stable; and &os.current;.</para>
</listitem>
<listitem>
<para>How to rebuild and reinstall the entire base
system with <command>make buildworld</command> (etc).</para>
</listitem>
</itemizedlist>
<para>Before reading this chapter, you should:</para>
<itemizedlist>
<listitem>
<para>Properly set up your network connection (<xref
linkend="advanced-networking"/>).</para>
</listitem>
<listitem>
<para>Know how to install additional third-party
software (<xref linkend="ports"/>).</para>
</listitem>
</itemizedlist>
<note>
<para>Throughout this chapter, the <command>svn</command>
command is used to obtain and update &os; sources. To use it,
you will need to install the port or the package for <filename
role="package">devel/subversion</filename>.</para>
</note>
</sect1>
<sect1 id="updating-upgrading-freebsdupdate">
<sect1info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Colin</firstname>
<surname>Percival</surname>
<contrib>Based on notes provided by </contrib>
</author>
</authorgroup>
</sect1info>
<title>FreeBSD Update</title>
<indexterm><primary>Updating and Upgrading</primary></indexterm>
<indexterm>
<primary>freebsd-update</primary>
<see>updating-upgrading</see>
</indexterm>
<para>Applying security patches is an important part of
maintaining computer software, especially the operating system.
For the longest time on &os; this process was not an easy one.
Patches had to be applied to the source code, the code rebuilt
into binaries, and then the binaries had to be
re-installed.</para>
<para>This is no longer the case as &os; now includes a utility
simply called <command>freebsd-update</command>. This utility
provides two separate functions. First, it allows for binary
security and errata updates to be applied to the &os; base
system without the build and install requirements. Second, the
utility supports minor and major release upgrades.</para>
<note>
<para>Binary updates are available for all architectures and
releases currently supported by the security team.
Before updating to a new release, the current
release announcements should be reviewed as they may contain
important information pertinent to the desired release. These
announcements may be viewed at the following link:
<ulink url="http://www.FreeBSD.org/releases/"></ulink>.</para>
</note>
<para>If a <command>crontab</command> utilizing the features
of &man.freebsd-update.8; exists, it must be
disabled before the following operation is started.</para>
<sect2 id="freebsdupdate-config-file">
<title>The Configuration File</title>
<para>Some users may wish to tweak the default configuration
file in <filename>/etc/freebsd-update.conf</filename>,
allowing better control of the process. The options are very
well documented, but the following few may require a bit more
explanation:</para>
<programlisting># Components of the base system which should be kept updated.
Components src world kernel</programlisting>
<para>This parameter controls what parts of &os; will be kept up
to date. The default is to update the source code, the entire
base system, and the kernel. Components are the same as those
available during the install, for instance, adding
<literal>world/games</literal> here would allow game patches
to be applied. Using <literal>src/bin</literal> would allow
the source code in
<filename class="directory">src/bin</filename> to be
updated.</para>
<para>The best option is to leave this at the default as
changing it to include specific items will require the user
to list every item they prefer to be updated. This could
have disastrous consequences as source code and binaries may
become out of sync.</para>
<programlisting># Paths which start with anything matching an entry in an IgnorePaths
# statement will be ignored.
IgnorePaths</programlisting>
<para>Add paths, such as
<filename class="directory">/bin</filename> or
<filename class="directory">/sbin</filename> to leave these
specific directories untouched during the update
process. This option may be used to prevent
<command>freebsd-update</command> from overwriting local
modifications.</para>
<programlisting># Paths which start with anything matching an entry in an UpdateIfUnmodified
# statement will only be updated if the contents of the file have not been
# modified by the user (unless changes are merged; see below).
UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile</programlisting>
<para>Update configuration files in the specified directories
only if they have not been modified. Any changes made by the
user will invalidate the automatic updating of these files.
There is another option,
<literal>KeepModifiedMetadata</literal>, which will instruct
<command>freebsd-update</command> to save the changes during
the merge.</para>
<programlisting># When upgrading to a new &os; release, files which match MergeChanges
# will have any local changes merged into the version from the new release.
MergeChanges /etc/ /var/named/etc/</programlisting>
<para>List of directories with configuration files that
<command>freebsd-update</command> should attempt merges in.
The file merge process is a series of &man.diff.1; patches
similar to &man.mergemaster.8; with fewer options, the merges
are either accepted, open an editor, or
<command>freebsd-update</command> will abort. When in doubt,
backup <filename class="directory">/etc</filename> and just
accept the merges. See <xref linkend="mergemaster"/> for more
information about the <command>mergemaster</command>
command.</para>
<programlisting># Directory in which to store downloaded updates and temporary
# files used by &os; Update.
# WorkDir /var/db/freebsd-update</programlisting>
<para>This directory is where all patches and temporary
files will be placed. In cases where the user is doing
a version upgrade, this location should have a least a
gigabyte of disk space available.</para>
<programlisting># When upgrading between releases, should the list of Components be
# read strictly (StrictComponents yes) or merely as a list of components
# which *might* be installed of which &os; Update should figure out
# which actually are installed and upgrade those (StrictComponents no)?
# StrictComponents no</programlisting>
<para>When set to <literal>yes</literal>,
<command>freebsd-update</command> will assume that the
<literal>Components</literal> list is complete and will not
attempt to make changes outside of the list. Effectively,
<command>freebsd-update</command> will attempt to update
every file which belongs to the <literal>Components</literal>
list.</para>
</sect2>
<sect2 id="freebsdupdate-security-patches">
<title>Security Patches</title>
<para>Security patches are stored on a remote machine and
may be downloaded and installed using the following
command:</para>
<screen>&prompt.root; <userinput>freebsd-update fetch</userinput>
&prompt.root; <userinput>freebsd-update install</userinput></screen>
<para>If any kernel patches have been applied the system will
need a reboot. If all went well the system should be patched
and <command>freebsd-update</command> may be run as a nightly
&man.cron.8; job. An entry in
<filename>/etc/crontab</filename> would be sufficient to
accomplish this task:</para>
<programlisting>@daily root freebsd-update cron</programlisting>
<para>This entry states that once every day, the
<command>freebsd-update</command> utility will be run. In
this way, using the <option>cron</option> argument,
<command>freebsd-update</command> will only check if updates
exist. If patches exist, they will automatically be
downloaded to the local disk but not applied. The
<username>root</username> user will be sent an email so they
may install them manually.</para>
<para>If anything went wrong, <command>freebsd-update</command>
has the ability to roll back the last set of changes with
the following command:</para>
<screen>&prompt.root; <userinput>freebsd-update rollback</userinput></screen>
<para>Once complete, the system should be restarted if the
kernel or any kernel modules were modified. This will allow
&os; to load the new binaries into memory.</para>
<para>The <command>freebsd-update</command> utility can
automatically update the <filename>GENERIC</filename> kernel
only. If a custom kernel is in use, it will have to be
rebuilt and reinstalled after
<command>freebsd-update</command> finishes installing the rest
of the updates. However, <command>freebsd-update</command>
will detect and update the <filename>GENERIC</filename> kernel
in
<filename class="directory">/boot/GENERIC</filename> (if it
exists), even if it is not the current (running) kernel of the
system.</para>
<note>
<para>It is a good idea to always keep a copy of the
<filename>GENERIC</filename> kernel in
<filename class="directory">/boot/GENERIC</filename>. It
will be helpful in diagnosing a variety of problems, and in
performing version upgrades using
<command>freebsd-update</command> as described in
<xref linkend="freebsdupdate-upgrade"/>.</para>
</note>
<para>Unless the default configuration in
<filename>/etc/freebsd-update.conf</filename> has been
changed, <command>freebsd-update</command> will install the
updated kernel sources along with the rest of the updates.
Rebuilding and reinstalling your new custom kernel can then be
performed in the usual way.</para>
<note>
<para>The updates distributed via
<command>freebsd-update</command>, do not always involve the
kernel. It will not be necessary to rebuild your custom
kernel if the kernel sources have not been modified by the
execution of <command>freebsd-update install</command>.
However, <command>freebsd-update</command> will always
update the <filename>/usr/src/sys/conf/newvers.sh</filename>
file. The current patch level (as indicated by the
<literal>-p</literal> number reported by
<command>uname -r</command>) is obtained from this file.
Rebuilding your custom kernel, even if nothing else changed,
will allow &man.uname.1; to accurately report the current
patch level of the system. This is particularly helpful
when maintaining multiple systems, as it allows for a quick
assessment of the updates installed in each one.</para>
</note>
</sect2>
<sect2 id="freebsdupdate-upgrade">
<title>Major and Minor Version Upgrades</title>
<para>Upgrades from one minor version of &os; to another, like
from &os; 9.0 to &os; 9.1, are called
<emphasis>minor version</emphasis> upgrades. Generally,
installed applications will continue to work without problems
after minor version upgrades.</para>
<para><emphasis>Major version</emphasis> upgrades are when &os;
is upgraded from one major version to another, like from
&os; 8.X to &os; 9.X. Major version upgrades will
remove old object files and libraries which will break most
third party applications. It is recommended that all
installed ports either be removed and re-installed or upgraded
after a major version upgrade by using the
<filename role="package">ports-mgmt/portupgrade</filename>
utility. A brute-force rebuild of all installed
applications can be accomplished with this command:</para>
<screen>&prompt.root; <userinput>portupgrade -af</userinput></screen>
<para>This will ensure everything will be re-installed
correctly. Note that setting the
<makevar>BATCH</makevar> environment variable to
<literal>yes</literal> will answer <literal>yes</literal> to
any prompts during this process, removing the need for
manual intervention during the build process.</para>
<sect3 id="freebsd-update-custom-kernel">
<title>Dealing with Custom Kernels</title>
<para>If a custom kernel is in use, the upgrade process is
slightly more involved, and the procedure varies depending
on the version of &os;.</para>
<sect4 id="freebsd-update-custom-kernel-8x">
<title>Custom Kernels with &os; 8.X and Earlier</title>
<para>A copy of the
<filename>GENERIC</filename> kernel is needed, and it
should be placed in <filename
class="directory">/boot/GENERIC</filename>. If the
<filename>GENERIC</filename> kernel is not already present
in the system, it may be obtained using one of the
following methods:</para>
<itemizedlist>
<listitem>
<para>If a custom kernel has only been built once, the
kernel in <filename
class="directory">/boot/kernel.old</filename> is
actually the <filename>GENERIC</filename> one. Simply
rename this directory to <filename
class="directory">/boot/GENERIC</filename>.</para>
</listitem>
<listitem>
<para>Assuming physical access to the machine is
possible, a copy of the <filename>GENERIC</filename>
kernel can be installed from the CD-ROM media. Insert
your installation disc and use the following
commands:</para>
<screen>&prompt.root; <userinput>mount /cdrom</userinput>
&prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput>
&prompt.root; <userinput>./install.sh GENERIC</userinput></screen>
<para>Replace <filename
class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
with the actual version of the release you are using.
The <filename>GENERIC</filename> kernel will be
installed in <filename
class="directory">/boot/GENERIC</filename> by
default.</para>
</listitem>
<listitem>
<para>Failing all the above, the
<filename>GENERIC</filename> kernel may be rebuilt and
installed from the sources:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput>
&prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput>
&prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>
<para>For this kernel to be picked up as
<filename>GENERIC</filename>
by <command>freebsd-update</command>, the
<filename>GENERIC</filename> configuration file must
not have been modified in any way. It is also
suggested that it is built without any other special
options.</para>
</listitem>
</itemizedlist>
<para>Rebooting to the <filename>GENERIC</filename> kernel
is not required at this stage.</para>
</sect4>
<sect4 id="freebsd-update-custom-kernel-9x">
<title>Custom Kernels with &os; 9.X and Later</title>
<itemizedlist>
<listitem>
<para>If a custom kernel has only been built once, the
kernel in
<filename
class="directory">/boot/kernel.old</filename>
is actually the <literal>GENERIC</literal> kernel.
Rename this directory to <filename
class="directory">/boot/kernel</filename>.</para>
</listitem>
<listitem>
<para>If physical access to the machine is available, a
copy of the <literal>GENERIC</literal> kernel can be
installed from the CD-ROM media. Load the
installation disc and use these commands:</para>
<screen>&prompt.root; <userinput>mount /cdrom</userinput>
&prompt.root; <userinput>cd /cdrom/usr/freebsd-dist</userinput>
&prompt.root; <userinput>tar -C/ -xvf kernel.txz boot/kernel/kernel</userinput></screen>
</listitem>
<listitem>
<para>If the options above cannot be used, the
<literal>GENERIC</literal> kernel may be rebuilt and
installed from the sources:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make kernel __MAKE_CONF=/dev/null SRCCONF=/dev/null</userinput></screen>
<para>For this kernel to be identified as the
<literal>GENERIC</literal> kernel by
<command>freebsd-update</command>, the
<filename>GENERIC</filename> configuration file must
not have been modified in any way. It is also
suggested that the kernel is built without any other
special options.</para>
</listitem>
</itemizedlist>
<para>Rebooting to the <filename>GENERIC</filename> kernel
is not required at this stage.</para>
</sect4>
</sect3>
<sect3 id="freebsdupdate-using">
<title>Performing the Upgrade</title>
<para>Major and minor version upgrades may be performed by
providing <command>freebsd-update</command> with a release
version target, for example, the following command will
update to &os; 8.1:</para>
<screen>&prompt.root; <userinput>freebsd-update -r 8.1-RELEASE upgrade</userinput></screen>
<para>After the command has been received,
<command>freebsd-update</command> will evaluate the
configuration file and current system in an attempt to
gather the information necessary to update the system. A
screen listing will display what components have been
detected and what components have not been detected. For
example:</para>
<screen>Looking up update.FreeBSD.org mirrors... 1 mirrors found.
Fetching metadata signature for 8.0-RELEASE from update1.FreeBSD.org... done.
Fetching metadata index... done.
Inspecting system... done.
The following components of FreeBSD seem to be installed:
kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games
src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue
src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin
world/base world/info world/lib32 world/manpages
The following components of FreeBSD do not seem to be installed:
kernel/generic world/catpages world/dict world/doc world/games
world/proflibs
Does this look reasonable (y/n)? y</screen>
<para>At this point, <command>freebsd-update</command> will
attempt to download all files required for the upgrade. In
some cases, the user may be prompted with questions
regarding what to install or how to proceed.</para>
<para>When using a custom kernel, the above step will produce
a warning similar to the following:</para>
<screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" kernel, which is not a
kernel configuration distributed as part of FreeBSD 8.0-RELEASE.
This kernel will not be updated: you MUST update the kernel manually
before running "/usr/sbin/freebsd-update install"</screen>
<para>This warning may be safely ignored at this point. The
updated <filename>GENERIC</filename> kernel will be used as
an intermediate step in the upgrade process.</para>
<para>After all patches have been downloaded to the local
system, they will then be applied. This process may take a
while depending on the speed and workload of the machine.
Configuration files will then be merged — this
part of the process requires some user intervention as a
file may be merged or an editor may appear on screen for a
manual merge. The results of every successful merge will be
shown to the user as the process continues. A failed or
ignored merge will cause the process to abort. Users may
wish to make a backup of <filename
class="directory">/etc</filename> and manually merge
important files, such as
<filename>master.passwd</filename> or
<filename>group</filename> at a later time.</para>
<note>
<para>The system is not being altered yet, all patching and
merging is happening in another directory. When all
patches have been applied successfully, all configuration
files have been merged and it seems the process will go
smoothly, the changes will need to be committed by the
user.</para>
</note>
<para>Once this process is complete, the upgrade may be
committed to disk using the following command.</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
<para>The kernel and kernel modules will be patched first. At
this point the machine must be rebooted. If the system was
running with a custom kernel, use the &man.nextboot.8;
command to set the kernel for the next boot to
<filename class="directory">/boot/GENERIC</filename> (which
was updated):</para>
<screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen>
<warning>
<para>Before rebooting with the <filename>GENERIC</filename>
kernel, make sure it contains all drivers required for
your system to boot properly (and connect to the network,
if the machine that is being updated is accessed
remotely). In particular, if the previously running
custom kernel contained built-in functionality usually
provided by kernel modules, make sure to temporarily load
these modules into the <filename>GENERIC</filename> kernel
using the <filename>/boot/loader.conf</filename> facility.
You may also wish to disable non-essential services, disk
and network mounts, etc. until the upgrade process is
complete.</para>
</warning>
<para>The machine should now be restarted with the updated
kernel:</para>
<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
<para>Once the system has come back online,
<command>freebsd-update</command> will need to be started
again. The state of the process has been saved and thus,
<command>freebsd-update</command> will not start from the
beginning, but will remove all old shared libraries and
object files. To continue to this stage, issue the
following command:</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
<note>
<para>Depending on whether any libraries version numbers got
bumped, there may only be two install phases instead of
three.</para>
</note>
</sect3>
<sect3 id="freebsdupdate-portsrebuild">
<title>Rebuilding Ports After a Major Version Upgrade</title>
<para>After a major version upgrade, all third party software
will now need to be rebuilt and re-installed. This is
required as installed software may depend on libraries which
have been removed during the upgrade process. The
<filename role="package">ports-mgmt/portupgrade</filename>
command may be used to automate this process. The following
commands may be used to begin this process:</para>
<screen>&prompt.root; <userinput>portupgrade -f ruby</userinput>
&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput>
&prompt.root; <userinput>portupgrade -f ruby18-bdb</userinput>
&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db</userinput>
&prompt.root; <userinput>portupgrade -af</userinput></screen>
<para>Once this has completed, finish the upgrade process with
a final call to <command>freebsd-update</command>. Issue
the following command to tie up all loose ends in the
upgrade process:</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
<para>If the <filename>GENERIC</filename> kernel was
temporarily used, this is the time to build and install a
new custom kernel in the usual way.</para>
<para>Reboot the machine into the new &os; version. The
process is complete.</para>
</sect3>
</sect2>
<sect2 id="freebsdupdate-system-comparison">
<title>System State Comparison</title>
<para>The <command>freebsd-update</command> utility may be used
to test the state of the installed &os; version against a
known good copy. This option evaluates the current version
of system utilities, libraries, and configuration files.
To begin the comparison, issue the following command:</para>
<screen>&prompt.root; <userinput>freebsd-update IDS >> outfile.ids</userinput></screen>
<warning>
<para>While the command name is <acronym>IDS</acronym> it
should in no way be a replacement for an intrusion detection
system such as
<filename role="package">security/snort</filename>. As
<command>freebsd-update</command> stores data on disk, the
possibility of tampering is evident. While this possibility
may be reduced by using the
<varname>kern.securelevel</varname> setting and storing the
<command>freebsd-update</command> data on a read only file
system when not in use, a better solution would be to
compare the system against a secure disk, such as a
<acronym>DVD</acronym> or securely stored external
<acronym>USB</acronym> disk device.</para>
</warning>
<para>The system will now be inspected, and a list of files
along with their &man.sha256.1; hash values, both the known
value in the release and the current installed value, will be
printed. This is why the output has been sent to the
<filename>outfile.ids</filename> file. It scrolls by too
quickly for eye comparisons, and soon it fills up the console
buffer.</para>
<para>These lines are also extremely long, but the output format
may be parsed quite easily. For instance, to obtain a list of
all files different from those in the release, issue the
following command:</para>
<screen>&prompt.root; <userinput>cat outfile.ids | awk '{ print $1 }' | more</userinput>
/etc/master.passwd
/etc/motd
/etc/passwd
/etc/pf.conf</screen>
<para>This output has been truncated, many more files exist.
Some of these files have natural modifications, the
<filename>/etc/passwd</filename> has been modified because
users have been added to the system. In some cases, there
may be other files, such as kernel modules, which differ
as <command>freebsd-update</command> may have updated them.
To exclude specific files or directories, add them to the
<literal>IDSIgnorePaths</literal> option in
<filename>/etc/freebsd-update.conf</filename>.</para>
<para>This system may be used as part of an elaborate upgrade
method, aside from the previously discussed version.</para>
</sect2>
</sect1>
<sect1 id="updating-upgrading-portsnap">
<sect1info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Written by </contrib>
</author>
</authorgroup>
<authorgroup>
<author>
<firstname>Colin</firstname>
<surname>Percival</surname>
<contrib>Based on notes provided by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Portsnap: a Ports Collection Update Tool</title>
<indexterm><primary>Updating and Upgrading</primary></indexterm>
<indexterm>
<primary>Portsnap</primary>
<see>Updating and Upgrading</see>
</indexterm>
<para>The base system of &os; includes a utility for updating
the Ports Collection too: the &man.portsnap.8; utility. Upon
execution, it will connect to a remote site, verify the secure
key, and download a new copy of the Ports Collection. The key
is used to verify the integrity of all downloaded files,
ensuring they have not been modified in-flight. To download the
latest Ports Collection files, issue the following
command:</para>
<screen>&prompt.root; <userinput>portsnap fetch</userinput>
Looking up portsnap.FreeBSD.org mirrors... 9 mirrors found.
Fetching snapshot tag from geodns-1.portsnap.freebsd.org... done.
Fetching snapshot metadata... done.
Updating from Tue May 22 02:12:15 CEST 2012 to Wed May 23 16:28:31 CEST 2012.
Fetching 3 metadata patches.. done.
Applying metadata patches... done.
Fetching 3 metadata files... done.
Fetching 90 patches.....10....20....30....40....50....60....70....80....90. done.
Applying patches... done.
Fetching 133 new ports or files... done.</screen>
<para>What this example shows is that &man.portsnap.8; has found
and verified several patches to the current ports data. This
also indicates that the utility was run previously, if it was a
first time run, the collection would have simply been
downloaded.</para>
<para>When &man.portsnap.8; successfully completes a
<command>fetch</command> operation, the Ports Collection and
subsequent patches exist on the local system that have passed
verification. The first time <command>portsnap</command> is
executed, you have to use <literal>extract</literal> to install
the downloaded files:</para>
<screen>&prompt.root; <userinput>portsnap extract</userinput>
/usr/ports/.cvsignore
/usr/ports/CHANGES
/usr/ports/COPYRIGHT
/usr/ports/GIDs
/usr/ports/KNOBS
/usr/ports/LEGAL
/usr/ports/MOVED
/usr/ports/Makefile
/usr/ports/Mk/bsd.apache.mk
/usr/ports/Mk/bsd.autotools.mk
/usr/ports/Mk/bsd.cmake.mk
<replaceable>...</replaceable></screen>
<para>To update an already installed Ports Collection use the
command <command>portsnap update</command>:</para>
<screen>&prompt.root; <userinput>portsnap update</userinput></screen>
<para>The process is now complete, and applications may be
installed or upgraded using the updated Ports Collection.</para>
<para>The <literal>fetch</literal> and <literal>extract</literal>
or <literal>update</literal> operations may be run
consecutively, as shown in the following example:</para>
<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
<para>This command will download the latest version of the
Ports Collection and update your local version under
<filename class="directory">/usr/ports</filename>.</para>
</sect1>
<sect1 id="updating-upgrading-documentation">
<title>Updating the Documentation Set</title>
<indexterm><primary>Updating and Upgrading</primary></indexterm>
<indexterm>
<primary>Documentation</primary>
<see>Updating and Upgrading</see>
</indexterm>
<para>Besides the base system and the Ports Collection,
documentation is an integral part of the &os; operating system.
While an up-to-date version of the &os; Documentation Set is
always available on the
<ulink url="http://www.freebsd.org/doc/">&os; web site</ulink>,
some users might have slow or no permanent network connectivity
at all. Fortunately, there are several ways to update the
documentation shipped with each release by maintaining a local
copy of the latest &os; Documentation Set.</para>
<sect2 id="dsvn-doc">
<title>Using <application>Subversion</application> to Update the
Documentation</title>
<para>The &os; documentation sources can be obtained with
<application>Subversion</application>. This section
describes:</para>
<itemizedlist>
<listitem>
<para>How to install the documentation toolchain, the tools
that are required to rebuild the &os; documentation from
its source.</para>
</listitem>
<listitem>
<para>How to download a copy of the documentation source
at <filename class="directory">/usr/doc</filename>,
using <application>Subversion</application>.</para>
</listitem>
<listitem>
<para>How to rebuild the &os; documentation from its source,
and install it under <filename
class="directory">/usr/share/doc</filename>.</para>
</listitem>
<listitem>
<para>Some of the build options that are supported by the
build system of the documentation, i.e., the options that
build only some of the different language translations of
the documentation or the options that select a specific
output format.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2 id="installing-documentation-toolchain">
<title>Installing <application>Subversion</application> and the
Documentation Toolchain</title>
<para>Rebuilding the &os; documentation from source requires a
fairly large collection of tools. These tools are not part of
the &os; base system, because they need a large amount of disk
space and they are not useful to all &os; users; they are only
useful to those users that are actively writing new
documentation for &os; or are frequently updating their
documentation from source.</para>
<para>All the required tools are available as part of the Ports
Collection. The
<filename role="package">textproc/docproj</filename> port is a
master port that has been developed by the &os; Documentation
Project, to ease the initial installation and future updates
of these tools.</para>
<note>
<para>When no &postscript; or PDF documentation required, one
might consider installing the <filename
role="package">textproc/docproj-nojadetex</filename> port
instead. This version of the documentation toolchain
includes everything except the
<application>teTeX</application> typesetting engine.
<application>teTeX</application> is a very large collection
of tools, so it may be quite sensible to omit its
installation if PDF output is not really necessary.</para>
</note>
<para><application>Subversion</application> is installed with
the <filename role="package">textproc/docproj</filename>
port.</para>
</sect2>
<sect2 id="updating-documentation-sources">
<title>Updating the Documentation Sources</title>
<para>The <application>Subversion</application> program can
fetch a clean copy of the documentation sources from the
western US mirror using the HTTPS protocol with this
command:</para>
<screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/doc/head /usr/doc</userinput></screen>
<para>Please use the closest mirror from the available <link
linkend="svn-mirrors">Subversion mirror sites</link>.</para>
<para>The initial download of the documentation sources may take
a while. Let it run until it completes.</para>
<para>Future updates of the documentation sources may be fetched
by running:</para>
<screen>&prompt.root; <userinput>svn update <filename class="directory">/usr/doc</filename></userinput></screen>
<para>After checking out the sources, an alternative way of
updating the documentation is supported by the
<filename>Makefile</filename> of the
<filename class="directory">/usr/doc</filename> directory by
running:</para>
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make update</userinput></screen>
</sect2>
<sect2 id="updating-documentation-options">
<title>Tunable Options of the Documentation Sources</title>
<para>The updating and build system of the &os; documentation
supports a few options that ease the process of updating only
parts of the documentation, or the build of specific
translations. These options can be set either as system-wide
options in the <filename>/etc/make.conf</filename> file, or as
command-line options passed to the &man.make.1;
utility.</para>
<para>The following options are some of these:</para>
<variablelist>
<varlistentry>
<term><makevar>DOC_LANG</makevar></term>
<listitem>
<para>The list of languages and encodings to build and
install, e.g., <literal>en_US.ISO8859-1</literal> for
the English documentation only.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><makevar>FORMATS</makevar></term>
<listitem>
<para>A single format or a list of output formats to be
built. Currently, <literal>html</literal>,
<literal>html-split</literal>, <literal>txt</literal>,
<literal>ps</literal>, <literal>pdf</literal>,
and <literal>rtf</literal> are supported.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><makevar>DOCDIR</makevar></term>
<listitem>
<para>Where to install the documentation. It defaults to
<filename
class="directory">/usr/share/doc</filename>.</para>
</listitem>
</varlistentry>
</variablelist>
<para>For more make variables supported as system-wide options
in &os;, see &man.make.conf.5;.</para>
<para>For more make variables supported by the build system of
the &os; documentation, please refer to the
<ulink url="&url.doc.langbase;/books/fdp-primer">&os;
Documentation Project Primer for New
Contributors</ulink>.</para>
</sect2>
<sect2 id="updating-installed-documentation">
<title>Installing the &os; Documentation from Source</title>
<para>When an up-to-date snapshot of the documentation sources
has been fetched in
<filename class="directory">/usr/doc</filename>, everything is
ready for an update of the installed documentation.</para>
<para>A full update of all the languages defined in
the <makevar>DOC_LANG</makevar> makefile option may be done by
typing:</para>
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
<para>If an update of only a specific language is desired,
&man.make.1; can be invoked in a language specific
subdirectory of
<filename class="directory">/usr/doc</filename>, i.e.:</para>
<screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
&prompt.root; <userinput>make update install clean</userinput></screen>
<para>The output formats that will be installed may be specified
by setting the <makevar>FORMATS</makevar> make variable,
i.e.:</para>
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>
<para>For information on editing and submitting corrections to
the documentation, please see the <ulink
url="&url.books.fdp-primer;">FreeBSD Documentation
Project Primer for New Contributors</ulink>.</para>
</sect2>
<sect2 id="doc-ports">
<sect2info>
<authorgroup>
<author>
<firstname>Marc</firstname>
<surname>Fonvieille</surname>
<contrib>Based on the work of </contrib>
</author>
</authorgroup>
</sect2info>
<title>Using Documentation Ports</title>
<indexterm><primary>Updating and Upgrading</primary></indexterm>
<indexterm>
<primary>documentation package</primary>
<see>Updating and Upgrading</see>
</indexterm>
<para>In the previous section, we have presented a method for
updating the &os; documentation from sources. Source based
updates may not be feasible or practical for all &os; systems
though. Building the documentation sources requires a fairly
large collection of tools and utilities, the
<emphasis>documentation toolchain</emphasis>, a certain level
of familiarity with <application>Subversion</application> and
source checkouts from a repository, and a few manual steps to
build the checked out sources. In this section, we describe
an alternative way of updating the installed copies of the
&os; documentation; one that uses the Ports Collection
and makes it possible to:</para>
<itemizedlist>
<listitem>
<para>Download and install pre-built snaphots of the
documentation, without having to locally build anything
(eliminating this way the need for an installation of the
entire documentation toolchain).</para>
</listitem>
<listitem>
<para>Download the documentation sources and build them
through the ports framework (making the checkout and build
steps a bit eaiser).</para>
</listitem>
</itemizedlist>
<para>These two methods of updating the &os; documentation are
supported by a set of
<emphasis>documentation ports</emphasis>, updated by the
&a.doceng; on a monthly basis. These are listed in the &os;
Ports Collection, under the virtual category named <ulink
url="http://www.freshports.org/docs/">docs</ulink>.</para>
<sect3 id="doc-ports-install-make">
<title>Building and Installing Documentation Ports</title>
<para>The documentation ports use the ports building framework
to make documentation builds easier. They automate the
process of checking out the documentation source, running
&man.make.1; with the appropriate environment settings and
command-line options, and they make the installation or
deinstallation of documentation as easy as the installation
of any other &os; port or package.</para>
<note>
<para>As an extra feature, when the documentation ports are
built locally, they record a dependency to the
<emphasis>documentation toolchain</emphasis> ports, so the
latter is automatically installed too.</para>
</note>
<para>Organization of the documentation ports is as
follows:</para>
<itemizedlist>
<listitem>
<para>There is a <quote>master port</quote>,
<filename role="package">misc/freebsd-doc-en</filename>,
where the documentation port files can be found. It is
the base of all documentation ports. By default, it
builds the English documentation only.</para>
</listitem>
<listitem>
<para>There is an <quote>all in one port</quote>,
<filename
role="package">misc/freebsd-doc-all</filename>, and it
builds and installs all documentation in all available
languages.</para>
</listitem>
<listitem>
<para>Finally, there is a <quote>slave port</quote> for
each translation, e.g.: <filename
role="package">misc/freebsd-doc-hu</filename> for the
Hungarian-language documents. All of them depend on the
master port and install the translated documentation of
the respective language.</para>
</listitem>
</itemizedlist>
<para>To install a documentation port from source, issue the
following commands (as <username>root</username>):</para>
<screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
<para>This will build and install the English documentation in
split <acronym>HTML</acronym> format (the same as used on
<ulink url="http://www.FreeBSD.org"></ulink>) in the
<filename
class="directory">/usr/local/share/doc/freebsd</filename>
directory.</para>
<sect4 id="doc-ports-options">
<title>Common Knobs and Options</title>
<para>There are many options for modifying the default
behavior of the documentation ports. The following is
just a short list:</para>
<variablelist>
<varlistentry>
<term><makevar>WITH_HTML</makevar></term>
<listitem>
<para>Allows the build of the HTML format: a single
HTML file per document. The formatted documentation
is saved to a file called
<filename>article.html</filename>, or
<filename>book.html</filename>, as appropriate, plus
images.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><makevar>WITH_PDF</makevar></term>
<listitem>
<para>Allows the build of the &adobe; Portable
Document Format, for use with &adobe;
&acrobat.reader;,
<application>Ghostscript</application> or other PDF
readers. The formatted documentation is saved to a
file called <filename>article.pdf</filename> or
<filename>book.pdf</filename>, as
appropriate.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><makevar>DOCBASE</makevar></term>
<listitem>
<para>Where to install the documentation. It defaults
to <filename
class="directory">/usr/local/share/doc/freebsd</filename>.</para>
<note>
<para>Notice that the default target directory
differs from the directory used by the
<application>Subversion</application> method.
This is because we are installing a port, and
ports are usually installed under the <filename
class="directory">/usr/local</filename>
directory. This can be overridden by adding the
<makevar>PREFIX</makevar> variable.</para>
</note>
</listitem>
</varlistentry>
</variablelist>
<para>Here is a brief example on how to use the variables
mentioned above to install the Hungarian documentation in
Portable Document Format:</para>
<screen>&prompt.root; cd /usr/ports/misc/freebsd-doc-hu
&prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</screen>
</sect4>
</sect3>
<sect3 id="doc-ports-install-package">
<title>Using Documentation Packages</title>
<para>Building the documentation ports from source, as
described in the previous section, requires a local
installation of the documentation toolchain and a bit of
disk space for the build of the ports. When resources are
not available to install the documentation toolchain, or
because the build from sources would take too much disk
space, it is still possible to install pre-built snapshots
of the documentation ports.</para>
<para>The &a.doceng; prepares monthly snapshots of the &os;
documentation packages. These binary packages can be used
with any of the bundled package tools, like &man.pkg.add.1;,
&man.pkg.delete.1;, and so on.</para>
<note>
<para>When binary packages are used, the &os; documentation
will be installed in <emphasis>all</emphasis> available
formats for the given language.</para>
</note>
<para>For example, the following command will install the
latest pre-built package of the Hungarian
documentation:</para>
<screen>&prompt.root; <userinput>pkg_add -r hu-freebsd-doc</userinput></screen>
<note>
<para>Packages have the following name format that differs
from the corresponding port's name:
<literal><replaceable>lang</replaceable>-freebsd-doc</literal>.
Here <replaceable>lang</replaceable> is the short format
of the language code, i.e., <literal>hu</literal> for
Hungarian, or <literal>zh_cn</literal> for Simplified
Chinese.</para>
</note>
</sect3>
<sect3 id="doc-ports-update">
<title>Updating Documentation Ports</title>
<para>To update a previously installed documentation port, any
tool suitable for updating ports is sufficient. For
example, the following command updates the installed
Hungarian documentation via the
<filename role="package">ports-mgmt/portupgrade</filename>
tool by using packages only:</para>
<screen>&prompt.root; <userinput>portupgrade -PP hu-freebsd-doc</userinput></screen>
</sect3>
</sect2>
</sect1>
<sect1 id="current-stable">
<title>Tracking a Development Branch</title>
<indexterm><primary>-CURRENT</primary></indexterm>
<indexterm><primary>-STABLE</primary></indexterm>
<para>There are two development branches to FreeBSD: &os.current;
and &os.stable;. This section will explain a bit about each and
describe how to keep your system up-to-date with each respective
tree. &os.current; will be discussed first, then
&os.stable;.</para>
<sect2 id="current">
<title>Staying Current with &os;</title>
<para>As you read this, keep in mind that &os.current; is the
<quote>bleeding edge</quote> of &os; development.
&os.current; users are expected to have a high degree of
technical skill, and should be capable of solving difficult
system problems on their own. If you are new to &os;, think
twice before installing it.</para>
<sect3>
<title>What Is &os.current;?</title>
<indexterm><primary>snapshot</primary></indexterm>
<para>&os.current; is the latest working sources for &os;.
This includes work in progress, experimental changes, and
transitional mechanisms that might or might not be present
in the next official release of the software. While many
&os; developers compile the &os.current; source code daily,
there are periods of time when the sources are not
buildable. These problems are resolved as expeditiously as
possible, but whether or not &os.current; brings disaster or
greatly desired functionality can be a matter of which exact
moment you grabbed the source code in!</para>
</sect3>
<sect3>
<title>Who Needs &os.current;?</title>
<para>&os.current; is made available for 3 primary
interest groups:</para>
<orderedlist>
<listitem>
<para>Members of the &os; community who are actively
working on some part of the source tree and for whom
keeping <quote>current</quote> is an absolute
requirement.</para>
</listitem>
<listitem>
<para>Members of the &os; community who are active
testers, willing to spend time solving problems in order
to ensure that &os.current; remains as sane as possible.
These are also people who wish to make topical
suggestions on changes and the general direction of
&os;, and submit patches to implement them.</para>
</listitem>
<listitem>
<para>Those who merely wish to keep an eye on things, or
to use the current sources for reference purposes
(e.g., for <emphasis>reading</emphasis>, not running).
These people also make the occasional comment or
contribute code.</para>
</listitem>
</orderedlist>
</sect3>
<sect3>
<title>What Is &os.current; <emphasis>Not</emphasis>?</title>
<orderedlist>
<listitem>
<para>A fast-track to getting pre-release bits because you
heard there is some cool new feature in there and you
want to be the first on your block to have it. Being
the first on the block to get the new feature means that
you are the first on the block to get the new
bugs.</para>
</listitem>
<listitem>
<para>A quick way of getting bug fixes. Any given version
of &os.current; is just as likely to introduce new bugs
as to fix existing ones.</para>
</listitem>
<listitem>
<para>In any way <quote>officially supported</quote>. We
do our best to help people genuinely in one of the 3
<quote>legitimate</quote> &os.current; groups, but we
simply <emphasis>do not have the time</emphasis> to
provide tech support. This is not because we are mean
and nasty people who do not like helping people out (we
would not even be doing &os; if we were). We simply
cannot answer hundreds messages a day
<emphasis>and</emphasis> work on FreeBSD! Given the
choice between improving &os; and answering lots of
questions on experimental code, the developers opt for
the former.</para>
</listitem>
</orderedlist>
</sect3>
<sect3>
<title>Using &os.current;</title>
<indexterm>
<primary>-CURRENT</primary>
<secondary>using</secondary>
</indexterm>
<orderedlist>
<listitem>
<para>Join the &a.current.name; and the
&a.svn-src-head.name; lists. This is not just a good
idea, it is <emphasis>essential</emphasis>. If you are
not on the <emphasis>&a.current.name;</emphasis> list,
you will not see the comments that people are making
about the current state of the system and thus will
probably end up stumbling over a lot of problems that
others have already found and solved. Even more
importantly, you will miss out on important bulletins
which may be critical to your system's continued
health.</para>
<para>The &a.svn-src-head.name; list will allow you to see
the commit log entry for each change as it is made,
along with any pertinent information on possible
side-effects.</para>
<para>To join these lists, or one of the others available
go to &a.mailman.lists.link; and click on the list that
you wish to subscribe to. Instructions on the rest of
the procedure are available there. If you are
interested in tracking changes for the whole source
tree, we would recommend subscribing to the
&a.svn-src-all.name; list.</para>
</listitem>
<listitem>
<para>Grab the sources from a &os;
<link linkend="mirrors">mirror site</link>. You can do
this in one of several ways:</para>
<orderedlist>
<indexterm>
<primary>Subversion</primary>
</indexterm>
<indexterm>
<primary><command>cron</command></primary>
</indexterm>
<indexterm>
<primary>-CURRENT</primary>
<secondary>Syncing with
<application>Subversion</application>
</secondary>
</indexterm>
<indexterm>
<primary>-CURRENT</primary>
<secondary>Syncing with
<application>CTM</application>
</secondary>
</indexterm>
<listitem>
<para>Use the <link linkend="svn">svn</link> program
to check out the desired development or release
branch. This is the recommended method, providing
access to &os; development as it occurs. Checkout
the -CURRENT code from the <literal>head</literal>
branch of one of the
<link linkend="svn-mirrors">Subversion mirror
sites</link>. Because of the size of the
repository, it is recommended that only desired
subtrees be checked out.</para>
</listitem>
<listitem>
<indexterm>
<primary>-CURRENT</primary>
<secondary>Syncing with CTM</secondary>
</indexterm>
<para>Use the <application><link
linkend="ctm">CTM</link></application> facility.
If you have very bad connectivity (high price
connections or only email access)
<application>CTM</application> is an option.
However, it is a lot of hassle and can give you
broken files. This leads to it being rarely used,
which again increases the chance of it not working
for fairly long periods of time. We recommend using
<application><link
linkend="svn">Subversion</link></application> for
any system with Internet connectivity.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>If you are grabbing the sources to run, and not just
look at, then grab <emphasis>all</emphasis> of
&os.current;, not just selected portions. The reason
for this is that various parts of the source depend on
updates elsewhere, and trying to compile just a subset
is almost guaranteed to get you into trouble.</para>
<indexterm>
<primary>-CURRENT</primary>
<secondary>compiling</secondary>
</indexterm>
<para>Before compiling &os.current;, read the
<filename>Makefile</filename> in
<filename>/usr/src</filename> carefully. You should at
least <link linkend="makeworld">install a new kernel and
rebuild the world</link> the first time through as part
of the upgrading process. Reading the &a.current; and
<filename>/usr/src/UPDATING</filename> will keep you
up-to-date on other bootstrapping procedures that
sometimes become necessary as we move toward the next
release.</para>
</listitem>
<listitem>
<para>Be active! If you are running &os.current;, we want
to know what you have to say about it, especially if you
have suggestions for enhancements or bug fixes.
Suggestions with accompanying code are received most
enthusiastically!</para>
</listitem>
</orderedlist>
</sect3>
</sect2>
<sect2 id="stable">
<title>Staying Stable with &os;</title>
<sect3>
<title>What Is &os.stable;?</title>
<indexterm><primary>-STABLE</primary></indexterm>
<para>&os.stable; is our development branch from which major
releases are made. Changes go into this branch at a
different pace, and with the general assumption that they
have first gone into &os.current; for testing. This is
<emphasis>still</emphasis> a development branch, however,
and this means that at any given time, the sources for
&os.stable; may or may not be suitable for any particular
purpose. It is simply another engineering development
track, not a resource for end-users.</para>
</sect3>
<sect3>
<title>Who Needs &os.stable;?</title>
<para>If you are interested in tracking or contributing to the
FreeBSD development process, especially as it relates to the
next <quote>point</quote> release of FreeBSD, then you
should consider following &os.stable;.</para>
<para>While it is true that security fixes also go into the
&os.stable; branch, you do not <emphasis>need</emphasis> to
track &os.stable; to do this. Every security advisory for
FreeBSD explains how to fix the problem for the releases it
affects
<footnote>
<para>That is not quite true. We can not continue
to support old releases of FreeBSD forever, although we
do support them for many years. For a complete
description of the current security policy for old
releases of FreeBSD, please see <ulink
url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para></footnote>,
and tracking an entire development branch just
for security reasons is likely to bring in a lot of unwanted
changes as well.</para>
<para>Although we endeavor to ensure that the &os.stable;
branch compiles and runs at all times, this cannot be
guaranteed. In addition, while code is developed in
&os.current; before including it in &os.stable;, more people
run &os.stable; than &os.current;, so it is inevitable that
bugs and corner cases will sometimes be found in &os.stable;
that were not apparent in &os.current;.</para>
<para>For these reasons, we do <emphasis>not</emphasis>
recommend that you blindly track &os.stable;, and it is
particularly important that you do not update any production
servers to &os.stable; without first thoroughly testing the
code in your development environment.</para>
<para>If you do not have the resources to do this then we
recommend that you run the most recent release of FreeBSD,
and use the binary update mechanism to move from release to
release.</para>
</sect3>
<sect3>
<title>Using &os.stable;</title>
<indexterm>
<primary>-STABLE</primary>
<secondary>using</secondary>
</indexterm>
<orderedlist>
<listitem>
<para>Join the &a.stable.name; list. This will keep you
informed of build-dependencies that may appear in
&os.stable; or any other issues requiring special
attention. Developers will also make announcements in
this mailing list when they are contemplating some
controversial fix or update, giving the users a chance
to respond if they have any issues to raise concerning
the proposed change.</para>
<para>Join the relevant <application>SVN</application>
list for the branch you are tracking. For example, if
you are tracking the 9-STABLE branch, join the
&a.svn-src-stable-9.name; list. This will allow you to
view the commit log entry for each change as it is made,
along with any pertinent information on possible
side-effects.</para>
<para>To join these lists, or one of the others available
go to &a.mailman.lists.link; and click on the list that
you wish to subscribe to. Instructions on the rest of
the procedure are available there. If you are
interested in tracking changes for the whole source
tree, we would recommend subscribing to the
&a.svn-src-all.name; list.</para>
</listitem>
<listitem>
<para>If you are going to install a new system and want it
to run monthly snapshot built from &os.stable;, please
check the
<ulink url="&url.base;/snapshots/">Snapshots</ulink> web
page for more information. Alternatively, it is
possible to install the most recent &os.stable; release
from the <link linkend="mirrors">mirror sites</link> and
follow the instructions below to upgrade your system to
the most up to date &os.stable; source code.</para>
<para>If you are already running a previous release of
&os; and wish to upgrade via sources then you can easily
do so from a &os;
<link linkend="mirrors">mirror site</link>. This can be
done in one of several ways:</para>
<orderedlist>
<indexterm>
<primary>Subversion</primary>
</indexterm>
<indexterm>
<primary><command>cron</command></primary>
</indexterm>
<indexterm>
<primary>-STABLE</primary>
<secondary>syncing with
<application>Subversion</application></secondary>
</indexterm>
<listitem>
<para>Use the <link linkend="svn">svn</link> program
to check out the desired development or release
branch. This is the recommended method, providing
access to &os; development as it occurs. Branch
names include <literal>head</literal> for the
current development head, and branches identified in
<ulink url="&url.base;/releng/">the release
engineering page</ulink>, such as
<literal>stable/9</literal> or
<literal>releng/9.0</literal>. URL
prefixes for <application>Subversion</application>
checkout of the base system are shown in <link
linkend="svn-mirrors">Subversion mirror
sites</link>.
Because of the size of the repository, it is
recommended that only desired subtrees be checked
out.</para>
</listitem>
<listitem>
<indexterm>
<primary>-STABLE</primary>
<secondary>syncing with CTM</secondary>
</indexterm>
<para>Use the <application><link
linkend="ctm">CTM</link></application> facility.
If you do not have a fast and inexpensive connection
to the Internet, this is the method you should
consider using.</para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>Essentially, if you need rapid on-demand access to
the source and communications bandwidth is not a
consideration, use
<application>Subversion</application>. Otherwise, use
<application>CTM</application>.</para>
</listitem>
<listitem>
<indexterm>
<primary>-STABLE</primary>
<secondary>compiling</secondary>
</indexterm>
<para>Before compiling &os.stable;, read the
<filename>Makefile</filename> in
<filename>/usr/src</filename> carefully. You should at
least <link linkend="makeworld">install a new kernel and
rebuild the world</link> the first time through as part
of the upgrading process. Reading the &a.stable; and
<filename>/usr/src/UPDATING</filename> will keep you
up-to-date on other bootstrapping procedures that
sometimes become necessary as we move toward the next
release.</para>
</listitem>
</orderedlist>
</sect3>
</sect2>
</sect1>
<sect1 id="synching">
<title>Synchronizing Your Source</title>
<para>There are various ways of using an Internet (or email)
connection to stay up-to-date with any given area of the &os;
project sources, or all areas, depending on what interests you.
The primary services we offer are
<link linkend="svn">Subversion</link> and
<link linkend="ctm">CTM</link>.</para>
<warning>
<para>While it is possible to update only parts of your source
tree, the only supported update procedure is to update the
entire tree and recompile both userland (i.e., all the
programs that run in user space, such as those in
<filename>/bin</filename> and <filename>/sbin</filename>) and
kernel sources. Updating only part of your source tree, only
the kernel, or only userland will often result in problems.
These problems may range from compile errors to kernel panics
or data corruption.</para>
</warning>
<indexterm>
<primary>Subversion</primary>
</indexterm>
<para><application>Subversion</application> uses the
<emphasis>pull</emphasis> model of updating sources. The user
(or a <command>cron</command> script) invokes the
<command>svn</command> program, and it brings files up-to-date.
<application>Subversion</application> is the preferred means of
updating local source trees. The updates you receive are
up-to-the-minute and you get them when, and only when, you want
them. You can easily restrict your updates to the specific
files or directories that are of interest to you. Updates are
generated on the fly by the server, according to what you have
and what you want to have.</para>
<indexterm>
<primary><application>CTM</application></primary>
</indexterm>
<para><application>CTM</application>, on the other hand, does not
interactively compare the sources you have with those on the
master archive or otherwise pull them across. Instead, a script
which identifies changes in files since its previous run is
executed several times a day on the master CTM machine, any
detected changes being compressed, stamped with a
sequence-number and encoded for transmission over email (in
printable ASCII only). Once received, these
<quote>CTM deltas</quote> can then be handed to the
&man.ctm.rmail.1; utility which will automatically decode,
verify and apply the changes to the user's copy of the sources.
This process is far more efficient than
<application>Subversion</application>, and places less strain on
our server resources since it is a <emphasis>push</emphasis>
rather than a <emphasis>pull</emphasis> model.</para>
<para>There are other trade-offs, of course. If you inadvertently
wipe out portions of your archive,
<application>Subversion</application> will detect and rebuild
the damaged portions for you. <application>CTM</application>
will not do this, and if you wipe some portion of your source
tree out (and do not have it backed up) then you will have to
start from scratch (from the most recent CTM
<quote>base delta</quote>) and rebuild it all with
<application>CTM</application>.</para>
</sect1>
<sect1 id="makeworld">
<title>Rebuilding <quote>world</quote></title>
<indexterm>
<primary>Rebuilding <quote>world</quote></primary>
</indexterm>
<para>Once you have synchronized your local source tree against a
particular version of &os; (&os.stable;, &os.current;, and so
on) you can then use the source tree to rebuild the
system.</para>
<warning>
<title>Make a Backup</title>
<para>It cannot be stressed enough how important it is to make a
backup of your system <emphasis>before</emphasis> you do this.
While rebuilding the world is (as long as you follow these
instructions) an easy task to do, there will inevitably be
times when you make mistakes, or when mistakes made by others
in the source tree render your system unbootable.</para>
<para>Make sure you have taken a backup. And have a fixit
floppy or bootable CD at hand. You will probably never have
to use it, but it is better to be safe than sorry!</para>
</warning>
<warning>
<title>Subscribe to the Right Mailing List</title>
<indexterm><primary>mailing list</primary></indexterm>
<para>The &os.stable; and &os.current; branches are, by their
nature, <emphasis>in development</emphasis>. People that
contribute to &os; are human, and mistakes occasionally
happen.</para>
<para>Sometimes these mistakes can be quite harmless, just
causing your system to print a new diagnostic warning. Or the
change may be catastrophic, and render your system unbootable
or destroy your file systems (or worse).</para>
<para>If problems like these occur, a <quote>heads up</quote> is
posted to the appropriate mailing list, explaining the nature
of the problem and which systems it affects. And an
<quote>all clear</quote> announcement is posted when the
problem has been solved.</para>
<para>If you try to track &os.stable; or &os.current; and do
not read the &a.stable; or the &a.current; respectively, then
you are asking for trouble.</para>
</warning>
<warning>
<title>Do Not Use <command>make world</command></title>
<para>A lot of older documentation recommends using
<command>make world</command> for this. Doing that skips
some important steps and should only be used if you are
sure of what you are doing. For almost all circumstances
<command>make world</command> is the wrong thing to do, and
the procedure described here should be used instead.</para>
</warning>
<sect2 id="canonical-build">
<title>The Canonical Way to Update Your System</title>
<para>To update your system, you should check
<filename>/usr/src/UPDATING</filename> for any pre-buildworld
steps necessary for your version of the sources and then use
the procedure outlined here.</para>
<para>These upgrade steps assume that you are currently using an
old &os; version, consisting of an old compiler, old kernel,
old world and old configuration files. By
<quote>world</quote> here we mean the core system binaries,
libraries and programming files. The compiler is part of
<quote>world</quote>, but has a few special concerns.</para>
<para>We also assume that you have already obtained the sources
to a newer system. If the sources available on the particular
system are old too, see <xref linkend="synching"/> for
detailed help about synchronizing them to a newer
version.</para>
<para>Updating the system from sources is a bit more subtle than
it might initially seem to be, and the &os; developers have
found it necessary over the years to change the recommended
approach fairly dramatically as new kinds of unavoidable
dependencies come to light. The rest of this section
describes the rationale behind the currently recommended
upgrade sequence.</para>
<para>Any successful update sequence must deal with the
following issues:</para>
<itemizedlist>
<listitem>
<para>The old compiler might not be able to compile the new
kernel. (Old compilers sometimes have bugs.) So, the new
kernel should be built with the new compiler. In
particular, the new compiler must be built before the new
kernel is built. This does not necessarily mean that the
new compiler must be <emphasis>installed</emphasis> before
building the new kernel.</para>
</listitem>
<listitem>
<para>The new world might rely on new kernel features. So,
the new kernel must be installed before the new world is
installed.</para>
</listitem>
</itemizedlist>
<para>These first two issues are the basis for the
core <maketarget>buildworld</maketarget>,
<maketarget>buildkernel</maketarget>,
<maketarget>installkernel</maketarget>,
<maketarget>installworld</maketarget> sequence that we
describe in the following paragraphs. This is not an
exhaustive list of all the reasons why you should prefer the
currently recommended upgrade process. Some of the less
obvious ones are listed below:</para>
<itemizedlist>
<listitem>
<para>The old world might not run correctly on the new
kernel, so you must install the new world immediately upon
installing the new kernel.</para>
</listitem>
<listitem>
<para>Some configuration changes must be done before the new
world is installed, but others might break the old world.
Hence, two different configuration upgrade steps are
generally needed.</para>
</listitem>
<listitem>
<para>For the most part, the update process only replaces or
adds files; existing old files are not deleted. In a few
cases, this can cause problems. As a result, the update
procedure will sometimes specify certain files that should
be manually deleted at certain steps. This may or may not
be automated in the future.</para>
</listitem>
</itemizedlist>
<para>These concerns have led to the following recommended
sequence. Note that the detailed sequence for particular
updates may require additional steps, but this core process
should remain unchanged for some time:</para>
<orderedlist>
<listitem>
<para><command>make
<maketarget>buildworld</maketarget></command></para>
<para>This first compiles the new compiler and a few related
tools, then uses the new compiler to compile the rest of
the new world. The result ends up in
<filename class="directory">/usr/obj</filename>.</para>
</listitem>
<listitem>
<para><command>make
<maketarget>buildkernel</maketarget></command></para>
<para>Unlike the older approach, using &man.config.8; and
&man.make.1;, this uses the <emphasis>new</emphasis>
compiler residing in
<filename class="directory">/usr/obj</filename>. This
protects you against compiler-kernel mismatches.</para>
</listitem>
<listitem>
<para><command>make
<maketarget>installkernel</maketarget></command></para>
<para>Place the new kernel and kernel modules onto the disk,
making it possible to boot with the newly updated
kernel.</para>
</listitem>
<listitem>
<para>Reboot into single user mode.</para>
<para>Single user mode minimizes problems from updating
software that is already running. It also minimizes any
problems from running the old world on a new
kernel.</para>
</listitem>
<listitem>
<para><command>mergemaster
<option>-p</option></command></para>
<para>This does some initial configuration file updates in
preparation for the new world. For instance it may add
new user groups to the system, or new user names to the
password database. This is often necessary when new
groups or special system-user accounts have been added
since the last update, so that the
<maketarget>installworld</maketarget> step will be able to
use the newly installed system user or system group names
without problems.</para>
</listitem>
<listitem>
<para><command>make
<maketarget>installworld</maketarget></command></para>
<para>Copies the world
from <filename class="directory">/usr/obj</filename>. You
now have a new kernel and new world on disk.</para>
</listitem>
<listitem>
<para><command>mergemaster</command></para>
<para>Now you can update the remaining configuration files,
since you have a new world on disk.</para>
</listitem>
<listitem>
<para>Reboot.</para>
<para>A full machine reboot is needed now to load the new
kernel and new world with new configuration files.</para>
</listitem>
</orderedlist>
<para>Note that if you are upgrading from one release of the
same &os; branch to a more recent release of the same branch,
i.e., from 7.0 to 7.1, then this procedure may not be
absolutely necessary, since you are unlikely to run into
serious mismatches between compiler, kernel, userland and
configuration files. The older approach of
<command>make <maketarget>world</maketarget></command>
followed by building and installing a new kernel might work
well enough for minor updates.</para>
<para>But, when upgrading across major releases, people who do
not follow this procedure should expect some problems.</para>
<para>It is also worth noting that many upgrades
(i.e., 4.<replaceable>X</replaceable> to 5.0) may require
specific additional steps (renaming or deleting specific files
prior to installworld, for instance). Read the
<filename>/usr/src/UPDATING</filename> file carefully,
especially at the end, where the currently recommended upgrade
sequence is explicitly spelled out.</para>
<para>This procedure has evolved over time as the developers
have found it impossible to completely prevent certain kinds
of mismatch problems. Hopefully, the current procedure will
remain stable for a long time.</para>
<para>To summarize, the currently recommended way of upgrading
&os; from sources is:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildworld</userinput>
&prompt.root; <userinput>make buildkernel</userinput>
&prompt.root; <userinput>make installkernel</userinput>
&prompt.root; <userinput>shutdown -r now</userinput></screen>
<note>
<para>There are a few rare cases when an extra run of
<command>mergemaster -p</command> is needed before the
<maketarget>buildworld</maketarget> step. These are
described in <filename>UPDATING</filename>. In general,
though, you can safely omit this step if you are not
updating across one or more major &os; versions.</para>
</note>
<para>After <maketarget>installkernel</maketarget> finishes
successfully, you should boot in single user mode
(i.e., using <command>boot -s</command> from the loader
prompt). Then run:</para>
<screen>&prompt.root; <userinput>mount -u /</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput>
&prompt.root; <userinput>adjkerntz -i</userinput>
&prompt.root; <userinput>mergemaster -p</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput>
&prompt.root; <userinput>mergemaster</userinput>
&prompt.root; <userinput>reboot</userinput></screen>
<warning>
<title>Read Further Explanations</title>
<para>The sequence described above is only a short resume to
help you getting started. You should however read the
following sections to clearly understand each step,
especially if you want to use a custom kernel
configuration.</para>
</warning>
</sect2>
<sect2 id="src-updating">
<title>Read <filename>/usr/src/UPDATING</filename></title>
<para>Before you do anything else, read
<filename>/usr/src/UPDATING</filename> (or the equivalent file
wherever you have a copy of the source code). This file
should contain important information about problems you might
encounter, or specify the order in which you might have to run
certain commands. If <filename>UPDATING</filename>
contradicts something you read here,
<filename>UPDATING</filename> takes precedence.</para>
<important>
<para>Reading <filename>UPDATING</filename> is not an
acceptable substitute for subscribing to the correct mailing
list, as described previously. The two requirements are
complementary, not exclusive.</para>
</important>
</sect2>
<sect2 id="make-conf">
<title>Check <filename>/etc/make.conf</filename></title>
<indexterm>
<primary><filename>make.conf</filename></primary>
</indexterm>
<para>&man.make.1; options are shown in &man.make.conf.5; and
<filename>/usr/share/examples/etc/make.conf</filename>. These
settings can be added to <filename>/etc/make.conf</filename>
to control the way &man.make.1; runs and how it builds
programs. Changes to some settings can have far-reaching and
potentially surprising effects. Read the comments in both
locations and keep in mind that the defaults have been chosen
for a combination of performance and safety.</para>
<para>Options set in <filename>/etc/make.conf</filename> take
effect every time &man.make.1; is used, including compiling
applications from the Ports Collection or user-written C
programs, or building the &os; operating system itself.</para>
</sect2>
<sect2 id="src-conf">
<title>Check <filename>/etc/src.conf</filename></title>
<indexterm>
<primary><filename>src.conf</filename></primary>
</indexterm>
<para><filename>/etc/src.conf</filename> controls the building
of the operating system from source code. Unlike
<filename>/etc/make.conf</filename>, the contents of
<filename>/etc/src.conf</filename> only take effect when the
&os; operating system itself is being built. Descriptions of
the many options available for this file are shown in
&man.src.conf.5;. Be cautious about disabling seemingly
unneeded kernel modules and build options. Sometimes there
are unexpected or subtle interactions.</para>
</sect2>
<sect2 id="updating-etc">
<title>Update the Files in <filename>/etc</filename></title>
<para>The <filename>/etc</filename> directory contains a large
part of your system's configuration information, as well as
scripts that are run at system startup. Some of these scripts
change from version to version of FreeBSD.</para>
<para>Some of the configuration files are also used in the day
to day running of the system. In particular,
<filename>/etc/group</filename>.</para>
<para>There have been occasions when the installation part of
<command>make installworld</command> has expected certain
usernames or groups to exist. When performing an upgrade it
is likely that these users or groups did not exist. This
caused problems when upgrading. In some cases
<command>make buildworld</command> will check to see if these
users or groups exist.</para>
<para>An example of this is when the <username>smmsp</username>
user was added. Users had the installation process fail for
them when &man.mtree.8; was trying to create
<filename>/var/spool/clientmqueue</filename>.</para>
<para>The solution is to run &man.mergemaster.8; in
pre-buildworld mode by providing the <option>-p</option>
option. This will compare only those files that are essential
for the success of <maketarget>buildworld</maketarget> or
<maketarget>installworld</maketarget>.</para>
<tip>
<para>If you are feeling particularly paranoid, you can check
your system to see which files are owned by the group you
are renaming or deleting:</para>
<screen>&prompt.root; <userinput>find / -group <replaceable>GID</replaceable> -print</userinput></screen>
<para>will show all files owned by group
<replaceable>GID</replaceable> (which can be either a group
name or a numeric group ID).</para>
</tip>
</sect2>
<sect2 id="makeworld-singleuser">
<title>Drop to Single User Mode</title>
<indexterm><primary>single-user mode</primary></indexterm>
<para>You may want to compile the system in single user mode.
Apart from the obvious benefit of making things go slightly
faster, reinstalling the system will touch a lot of important
system files, all the standard system binaries, libraries,
include files and so on. Changing these on a running system
(particularly if you have active users on the system at the
time) is asking for trouble.</para>
<indexterm><primary>multi-user mode</primary></indexterm>
<para>Another method is to compile the system in multi-user
mode, and then drop into single user mode for the
installation. If you would like to do it this way, simply
hold off on the following steps until the build has completed.
You can postpone dropping to single user mode until you have
to <maketarget>installkernel</maketarget> or
<maketarget>installworld</maketarget>.</para>
<para>As the superuser, you can execute:</para>
<screen>&prompt.root; <userinput>shutdown now</userinput></screen>
<para>from a running system, which will drop it to single user
mode.</para>
<para>Alternatively, reboot the system, and at the boot prompt,
select the <quote>single user</quote> option. The system will
then boot single user. At the shell prompt you should then
run:</para>
<screen>&prompt.root; <userinput>fsck -p</userinput>
&prompt.root; <userinput>mount -u /</userinput>
&prompt.root; <userinput>mount -a -t ufs</userinput>
&prompt.root; <userinput>swapon -a</userinput></screen>
<para>This checks the file systems, remounts
<filename>/</filename> read/write, mounts all the other UFS
file systems referenced in <filename>/etc/fstab</filename> and
then turns swapping on.</para>
<note>
<para>If your CMOS clock is set to local time and not to GMT
(this is true if the output of the &man.date.1; command
does not show the correct time and zone),
you may also need to run the following command:</para>
<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
<para>This will make sure that your local time-zone settings
get set up correctly — without this, you may later run
into some problems.</para>
</note>
</sect2>
<sect2 id="cleaning-usr-obj">
<title>Remove <filename>/usr/obj</filename></title>
<para>As parts of the system are rebuilt they are placed in
directories which (by default) go under
<filename>/usr/obj</filename>. The directories shadow those
under <filename>/usr/src</filename>.</para>
<para>You can speed up the <command>make buildworld</command>
process, and possibly save yourself some dependency headaches
by removing this directory as well.</para>
<para>Some files below <filename>/usr/obj</filename> may have
the immutable flag set (see &man.chflags.1; for more
information) which must be removed first.</para>
<screen>&prompt.root; <userinput>cd /usr/obj</userinput>
&prompt.root; <userinput>chflags -R noschg *</userinput>
&prompt.root; <userinput>rm -rf *</userinput></screen>
</sect2>
<sect2 id="updating-upgrading-compilebase">
<title>Recompile the Base System</title>
<sect3>
<title>Saving the Output</title>
<para>It is a good idea to save the output you get from
running &man.make.1; to another file. If something goes
wrong you will have a copy of the error message. While this
might not help you in diagnosing what has gone wrong, it can
help others if you post your problem to one of the &os;
mailing lists.</para>
<para>The easiest way to do this is to use the &man.script.1;
command, with a parameter that specifies the name of the
file to save all output to. You would do this immediately
before rebuilding the world, and then type
<userinput>exit</userinput> when the process has
finished.</para>
<screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput>
Script started, output file is /var/tmp/mw.out
&prompt.root; <userinput>make TARGET</userinput>
<emphasis>… compile, compile, compile …</emphasis>
&prompt.root; <userinput>exit</userinput>
Script done, …</screen>
<para>If you do this, <emphasis>do not</emphasis> save the
output in <filename>/tmp</filename>. This directory may be
cleared next time you reboot. A better place to store it is
in <filename>/var/tmp</filename> (as in the previous
example) or in <username>root</username>'s home
directory.</para>
</sect3>
<sect3 id="make-buildworld">
<title>Compile the Base System</title>
<para>You must be in the <filename>/usr/src</filename>
directory:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
<para>(unless, of course, your source code is elsewhere, in
which case change to that directory instead).</para>
<indexterm><primary><command>make</command></primary></indexterm>
<para>To rebuild the world you use the &man.make.1; command.
This command reads instructions from the
<filename>Makefile</filename>, which describes how the
programs that comprise &os; should be rebuilt, the order in
which they should be built, and so on.</para>
<para>The general format of the command line you will type is
as follows:</para>
<screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen>
<para>In this example,
<option>-<replaceable>x</replaceable></option> is an option
that you would pass to &man.make.1;. See the &man.make.1;
manual page for an example of the options you can
pass.</para>
<para><option>-D<replaceable>VARIABLE</replaceable></option>
passes a variable to the <filename>Makefile</filename>. The
behavior of the <filename>Makefile</filename> is controlled
by these variables. These are the same variables as are set
in <filename>/etc/make.conf</filename>, and this provides
another way of setting them.</para>
<screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen>
<para>is another way of specifying that profiled libraries
should not be built, and corresponds with the</para>
<programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting>
<para>line in <filename>/etc/make.conf</filename>.</para>
<para><replaceable>target</replaceable> tells &man.make.1;
what you want to do. Each <filename>Makefile</filename>
defines a number of different <quote>targets</quote>, and
your choice of target determines what happens.</para>
<para>Some targets are listed in the
<filename>Makefile</filename>, but are not meant for you to
run. Instead, they are used by the build process to break
out the steps necessary to rebuild the system into a number
of sub-steps.</para>
<para>Most of the time you will not need to pass any
parameters to &man.make.1;, and so your command like will
look like this:</para>
<screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen>
<para>Where <replaceable>target</replaceable> will be one of
many build options. The first target should always be
<makevar>buildworld</makevar>.</para>
<para>As the names imply, <maketarget>buildworld</maketarget>
builds a complete new tree under
<filename>/usr/obj</filename>, and
<maketarget>installworld</maketarget>, another target,
installs this tree on the current machine.</para>
<para>Having separate options is very useful for two reasons.
First, it allows you to do the build safe in the knowledge
that no components of your running system will be affected.
The build is <quote>self hosted</quote>. Because of this,
you can safely run <maketarget>buildworld</maketarget> on a
machine running in multi-user mode with no fear of
ill-effects. It is still recommended that you run the
<maketarget>installworld</maketarget> part in single user
mode, though.</para>
<para>Secondly, it allows you to use NFS mounts to upgrade
multiple machines on your network. If you have three
machines, <hostid>A</hostid>, <hostid>B</hostid> and
<hostid>C</hostid> that you want to upgrade, run
<command>make buildworld</command> and
<command>make installworld</command> on <hostid>A</hostid>.
<hostid>B</hostid> and <hostid>C</hostid> should then NFS
mount <filename>/usr/src</filename> and
<filename>/usr/obj</filename> from <hostid>A</hostid>, and
you can then run <command>make installworld</command> to
install the results of the build on <hostid>B</hostid> and
<hostid>C</hostid>.</para>
<para>Although the <maketarget>world</maketarget> target still
exists, you are strongly encouraged not to use it.</para>
<para>Run</para>
<screen>&prompt.root; <userinput>make buildworld</userinput></screen>
<para>It is possible to specify a <option>-j</option> option
to <command>make</command> which will cause it to spawn
several simultaneous processes. This is most useful on
multi-CPU machines. However, since much of the compiling
process is IO bound rather than CPU bound it is also useful
on single CPU machines.</para>
<para>On a typical single-CPU machine you would run:</para>
<screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
<para>&man.make.1; will then have up to 4 processes running at
any one time. Empirical evidence posted to the mailing
lists shows this generally gives the best performance
benefit.</para>
<para>If you have a multi-CPU machine and you are using an SMP
configured kernel try values between 6 and 10 and see how
they speed things up.</para>
</sect3>
<sect3>
<title>Timings</title>
<indexterm>
<primary>rebuilding <quote>world</quote></primary>
<secondary>timings</secondary>
</indexterm>
<para>Many factors influence the build time, but fairly recent
machines may only take a one or two hours to build the
&os.stable; tree, with no tricks or shortcuts used during
the process. A &os.current; tree will take somewhat
longer.</para>
</sect3>
</sect2>
<sect2 id="new-kernel">
<title>Compile and Install a New Kernel</title>
<indexterm>
<primary>kernel</primary>
<secondary>compiling</secondary>
</indexterm>
<para>To take full advantage of your new system you should
recompile the kernel. This is practically a necessity, as
certain memory structures may have changed, and programs like
&man.ps.1; and &man.top.1; will fail to work until the kernel
and source code versions are the same.</para>
<para>The simplest, safest way to do this is to build and
install a kernel based on <filename>GENERIC</filename>. While
<filename>GENERIC</filename> may not have all the necessary
devices for your system, it should contain everything
necessary to boot your system back to single user mode. This
is a good test that the new system works properly. After
booting from <filename>GENERIC</filename> and verifying that
your system works you can then build a new kernel based on
your normal kernel configuration file.</para>
<para>On &os; it is important to
<link linkend="make-buildworld">build world</link> before
building a new kernel.</para>
<note>
<para>If you want to build a custom kernel, and already have a
configuration file, just use
<literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal>
like this:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput>
&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen>
</note>
<para>Note that if you have raised
<literal>kern.securelevel</literal> above 1
<emphasis>and</emphasis> you have set either the
<literal>noschg</literal> or similar flags to your kernel
binary, you might find it necessary to drop into single user
mode to use <maketarget>installkernel</maketarget>. Otherwise
you should be able to run both these commands from multi user
mode without problems. See &man.init.8; for details about
<literal>kern.securelevel</literal> and &man.chflags.1; for
details about the various file flags.</para>
</sect2>
<sect2 id="new-kernel-singleuser">
<title>Reboot into Single User Mode</title>
<indexterm><primary>single-user mode</primary></indexterm>
<para>You should reboot into single user mode to test the new
kernel works. Do this by following the instructions in
<xref linkend="makeworld-singleuser"/>.</para>
</sect2>
<sect2 id="make-installworld">
<title>Install the New System Binaries</title>
<para>You should now use <maketarget>installworld</maketarget>
to install the new system binaries.</para>
<para>Run</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput></screen>
<note>
<para>If you specified variables on the
<command>make buildworld</command> command line, you must
specify the same variables in the
<command>make installworld</command> command line. This
does not necessarily hold true for other options; for
example, <option>-j</option> must never be used with
<maketarget>installworld</maketarget>.</para>
<para>For example, if you ran:</para>
<screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>
<para>you must install the results with:</para>
<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
<para>otherwise it would try to install profiled libraries
that had not been built during the
<command>make buildworld</command> phase.</para>
</note>
</sect2>
<sect2 id="post-installworld-updates">
<title>Update Files Not Updated by
<command>make installworld</command></title>
<para>Remaking the world will not update certain directories (in
particular, <filename>/etc</filename>,
<filename>/var</filename> and <filename>/usr</filename>) with
new or changed configuration files.</para>
<para>The simplest way to update these files is to use
&man.mergemaster.8;, though it is possible to do it manually
if you would prefer to do that. Regardless of which way you
choose, be sure to make a backup of <filename>/etc</filename>
in case anything goes wrong.</para>
<sect3 id="mergemaster">
<sect3info>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Rhodes</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect3info>
<title><command>mergemaster</command></title>
<indexterm>
<primary>
<command>mergemaster</command>
</primary>
</indexterm>
<para>The &man.mergemaster.8; utility is a Bourne script that
will aid you in determining the differences between your
configuration files in <filename>/etc</filename>, and the
configuration files in the source tree
<filename>/usr/src/etc</filename>. This is the recommended
solution for keeping the system configuration files up to
date with those located in the source tree.</para>
<para>To begin simply type <command>mergemaster</command> at
your prompt, and watch it start going.
<command>mergemaster</command> will then build a temporary
root environment, from <filename>/</filename> down, and
populate it with various system configuration files. Those
files are then compared to the ones currently installed in
your system. At this point, files that differ will be shown
in &man.diff.1; format, with the <option>+</option> sign
representing added or modified lines, and <option>-</option>
representing lines that will be either removed completely,
or replaced with a new line. See the &man.diff.1; manual
page for more information about the &man.diff.1; syntax and
how file differences are shown.</para>
<para>&man.mergemaster.8; will then show you each file that
displays variances, and at this point you will have the
option of either deleting the new file (referred to as the
temporary file), installing the temporary file in its
unmodified state, merging the temporary file with the
currently installed file, or viewing the &man.diff.1;
results again.</para>
<para>Choosing to delete the temporary file will tell
&man.mergemaster.8; that we wish to keep our current file
unchanged, and to delete the new version. This option is
not recommended, unless you see no reason to change the
current file. You can get help at any time by typing
<keycap>?</keycap> at the &man.mergemaster.8; prompt. If
the user chooses to skip a file, it will be presented again
after all other files have been dealt with.</para>
<para>Choosing to install the unmodified temporary file will
replace the current file with the new one. For most
unmodified files, this is the best option.</para>
<para>Choosing to merge the file will present you with a text
editor, and the contents of both files. You can now merge
them by reviewing both files side by side on the screen, and
choosing parts from both to create a finished product. When
the files are compared side by side, the <keycap>l</keycap>
key will select the left contents and the <keycap>r</keycap>
key will select contents from your right. The final output
will be a file consisting of both parts, which can then be
installed. This option is customarily used for files where
settings have been modified by the user.</para>
<para>Choosing to view the &man.diff.1; results again will
show you the file differences just like &man.mergemaster.8;
did before prompting you for an option.</para>
<para>After &man.mergemaster.8; is done with the system files
you will be prompted for other options. &man.mergemaster.8;
may ask if you want to rebuild the password file and will
finish up with an option to remove left-over temporary
files.</para>
</sect3>
<sect3>
<title>Manual Update</title>
<para>If you wish to do the update manually, however, you
cannot just copy over the files from
<filename>/usr/src/etc</filename> to
<filename>/etc</filename> and have it work. Some of these
files must be <quote>installed</quote> first. This is
because the <filename>/usr/src/etc</filename> directory
<emphasis>is not</emphasis> a copy of what your
<filename>/etc</filename> directory should look like. In
addition, there are files that should be in
<filename>/etc</filename> that are not in
<filename>/usr/src/etc</filename>.</para>
<para>If you are using &man.mergemaster.8; (as recommended),
you can skip forward to the
<link linkend="updating-upgrading-rebooting">next
section</link>.</para>
<para>The simplest way to do this by hand is to install the
files into a new directory, and then work through them
looking for differences.</para>
<warning>
<title>Backup Your Existing
<filename>/etc</filename></title>
<para>Although, in theory, nothing is going to touch this
directory automatically, it is always better to be sure.
So copy your existing <filename>/etc</filename> directory
somewhere safe. Something like:</para>
<screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
<para><option>-R</option> does a recursive copy,
<option>-p</option> preserves times, ownerships on files
and suchlike.</para>
</warning>
<para>You need to build a dummy set of directories to install
the new <filename>/etc</filename> and other files into.
<filename>/var/tmp/root</filename> is a reasonable choice,
and there are a number of subdirectories required under this
as well.</para>
<screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput>
&prompt.root; <userinput>cd /usr/src/etc</userinput>
&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen>
<para>This will build the necessary directory structure and
install the files. A lot of the subdirectories that have
been created under <filename>/var/tmp/root</filename> are
empty and should be deleted. The simplest way to do this is
to:</para>
<screen>&prompt.root; <userinput>cd /var/tmp/root</userinput>
&prompt.root; <userinput>find -d . -type d | xargs rmdir 2>/dev/null</userinput></screen>
<para>This will remove all empty directories. (Standard error
is redirected to <filename>/dev/null</filename> to prevent
the warnings about the directories that are not
empty.)</para>
<para><filename>/var/tmp/root</filename> now contains all the
files that should be placed in appropriate locations below
<filename>/</filename>. You now have to go through each of
these files, determining how they differ with your existing
files.</para>
<para>Note that some of the files that will have been
installed in <filename>/var/tmp/root</filename> have a
leading <quote>.</quote>. At the time of writing the only
files like this are shell startup files in
<filename>/var/tmp/root/</filename> and
<filename>/var/tmp/root/root/</filename>, although there may
be others (depending on when you are reading this). Make
sure you use <command>ls -a</command> to catch them.</para>
<para>The simplest way to do this is to use &man.diff.1; to
compare the two files:</para>
<screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen>
<para>This will show you the differences between your
<filename>/etc/shells</filename> file and the new
<filename>/var/tmp/root/etc/shells</filename> file. Use
these to decide whether to merge in changes that you have
made or whether to copy over your old file.</para>
<tip>
<title>Name the New Root Directory
(<filename>/var/tmp/root</filename>) with a Time Stamp, so
You Can Easily Compare Differences Between
Versions</title>
<para>Frequently rebuilding the world means that you have to
update <filename>/etc</filename> frequently as well, which
can be a bit of a chore.</para>
<para>You can speed this process up by keeping a copy of the
last set of changed files that you merged into
<filename>/etc</filename>. The following procedure gives
one idea of how to do this.</para>
<procedure>
<step>
<para>Make the world as normal. When you want to update
<filename>/etc</filename> and the other directories,
give the target directory a name based on the current
date. If you were doing this on the 14th of February
1998 you could do the following:</para>
<screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput>
&prompt.root; <userinput>cd /usr/src/etc</userinput>
&prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \
distrib-dirs distribution</userinput></screen>
</step>
<step>
<para>Merge in the changes from this directory as
outlined above.</para>
<para><emphasis>Do not</emphasis> remove the
<filename>/var/tmp/root-19980214</filename> directory
when you have finished.</para>
</step>
<step>
<para>When you have downloaded the latest version of the
source and remade it, follow step 1. This will give
you a new directory, which might be called
<filename>/var/tmp/root-19980221</filename> (if you
wait a week between doing updates).</para>
</step>
<step>
<para>You can now see the differences that have been
made in the intervening week using &man.diff.1; to
create a recursive diff between the two
directories:</para>
<screen>&prompt.root; <userinput>cd /var/tmp</userinput>
&prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen>
<para>Typically, this will be a much smaller set of
differences than those between
<filename>/var/tmp/root-19980221/etc</filename> and
<filename>/etc</filename>. Because the set of
differences is smaller, it is easier to migrate those
changes across into your <filename>/etc</filename>
directory.</para>
</step>
<step>
<para>You can now remove the older of the two
<filename>/var/tmp/root-*</filename>
directories:</para>
<screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen>
</step>
<step>
<para>Repeat this process every time you need to merge
in changes to <filename>/etc</filename>.</para>
</step>
</procedure>
<para>You can use &man.date.1; to automate the generation of
the directory names:</para>
<screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
</tip>
</sect3>
</sect2>
<sect2 id="updating-upgrading-rebooting">
<title>Rebooting</title>
<para>You are now done. After you have verified that everything
appears to be in the right place you can reboot the system. A
simple &man.shutdown.8; should do it:</para>
<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
</sect2>
<sect2>
<title>Finished</title>
<para>You should now have successfully upgraded your &os;
system. Congratulations.</para>
<para>If things went slightly wrong, it is easy to rebuild a
particular piece of the system. For example, if you
accidentally deleted <filename>/etc/magic</filename> as part
of the upgrade or merge of <filename>/etc</filename>, the
&man.file.1; command will stop working. In this case, the fix
would be to run:</para>
<screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
&prompt.root; <userinput>make all install</userinput></screen>
</sect2>
<sect2 id="updating-questions">
<title>Questions</title>
<qandaset>
<qandaentry>
<question>
<para>Do I need to re-make the world for every
change?</para>
</question>
<answer>
<para>There is no easy answer to this one, as it depends
on the nature of the change. For example, if you just
ran <application>Subversion</application>, and it has
shown the following files as being updated:</para>
<screen><filename>src/games/cribbage/instr.c</filename>
<filename>src/games/sail/pl_main.c</filename>
<filename>src/release/sysinstall/config.c</filename>
<filename>src/release/sysinstall/media.c</filename>
<filename>src/share/mk/bsd.port.mk</filename></screen>
<para>it probably is not worth rebuilding the entire
world. You could just go to the appropriate
sub-directories and <command>make all install</command>,
and that is about it. But if something major changed,
for example <filename>src/lib/libc/stdlib</filename>
then you should either re-make the world, or at least
those parts of it that are statically linked (as well as
anything else you might have added that is statically
linked).</para>
<para>At the end of the day, it is your call. You might
be happy re-making the world every fortnight say, and
let changes accumulate over that fortnight. Or you
might want to re-make just those things that have
changed, and be confident you can spot all the
dependencies.</para>
<para>And, of course, this all depends on how often you
want to upgrade, and whether you are tracking
&os.stable; or &os.current;.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>My compile failed with lots of signal 11 (or other
signal number) errors. What has happened?</para>
</question>
<answer>
<indexterm><primary>signal 11</primary></indexterm>
<para>This is normally indicative of hardware problems.
(Re)making the world is an effective way to stress test
your hardware, and will frequently throw up memory
problems. These normally manifest themselves as the
compiler mysteriously dying on receipt of strange
signals.</para>
<para>A sure indicator of this is if you can restart the
make and it dies at a different point in the
process.</para>
<para>In this instance there is little you can do except
start swapping around the components in your machine to
determine which one is failing.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Can I remove <filename>/usr/obj</filename> when I
have finished?</para>
</question>
<answer>
<para>The short answer is yes.</para>
<para><filename>/usr/obj</filename> contains all the
object files that were produced during the compilation
phase. Normally, one of the first steps in the
<command>make buildworld</command> process is to remove
this directory and start afresh. In this case, keeping
<filename>/usr/obj</filename> around after you have
finished makes little sense, and will free up a large
chunk of disk space (currently about 2 GB).</para>
<para>However, if you know what you are doing you can have
<command>make buildworld</command> skip this step. This
will make subsequent builds run much faster, since most
of the sources will not need to be recompiled. The flip
side of this is that subtle dependency problems can
creep in, causing your build to fail in odd ways. This
frequently generates noise on the &os; mailing lists,
when one person complains that their build has failed,
not realizing that it is because they have tried to cut
corners.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Can interrupted builds be resumed?</para>
</question>
<answer>
<para>This depends on how far through the process you got
before you found a problem.</para>
<para><emphasis>In general</emphasis> (and this is not a
hard and fast rule) the
<command>make buildworld</command> process builds new
copies of essential tools (such as &man.gcc.1;, and
&man.make.1;) and the system libraries. These tools and
libraries are then installed. The new tools and
libraries are then used to rebuild themselves, and are
installed again. The entire system (now including
regular user programs, such as &man.ls.1; or
&man.grep.1;) is then rebuilt with the new system
files.</para>
<para>If you are at the last stage, and you know it
(because you have looked through the output that you
were storing) then you can (fairly safely) do:</para>
<screen><emphasis>… fix the problem …</emphasis>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen>
<para>This will not undo the work of the previous
<command>make buildworld</command>.</para>
<para>If you see the message:</para>
<screen>--------------------------------------------------------------
Building everything..
--------------------------------------------------------------</screen>
<para>in the <command>make buildworld</command> output
then it is probably fairly safe to do so.</para>
<para>If you do not see that message, or you are not sure,
then it is always better to be safe than sorry, and
restart the build from scratch.</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How can I speed up making the world?</para>
</question>
<answer>
<itemizedlist>
<listitem>
<para>Run in single user mode.</para>
</listitem>
<listitem>
<para>Put the <filename>/usr/src</filename> and
<filename>/usr/obj</filename> directories on
separate file systems held on separate disks. If
possible, put these disks on separate disk
controllers.</para>
</listitem>
<listitem>
<para>Better still, put these file systems across
multiple disks using the &man.ccd.4; (concatenated
disk driver) device.</para>
</listitem>
<listitem>
<para>Turn off profiling (set
<quote>NO_PROFILE=true</quote> in
<filename>/etc/make.conf</filename>). You almost
certainly do not need it.</para>
</listitem>
<listitem>
<para>Pass the
<option>-j<replaceable>n</replaceable></option>
option to &man.make.1; to run multiple processes in
parallel. This usually helps regardless of whether
you have a single or a multi processor
machine.</para>
</listitem>
<listitem>
<para>The file system holding
<filename>/usr/src</filename> can be mounted (or
remounted) with the <option>noatime</option> option.
This prevents the file system from recording the
file access time. You probably do not need this
information anyway.</para>
<screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen>
<warning>
<para>The example assumes
<filename>/usr/src</filename> is on its own file
system. If it is not (if it is a part of
<filename>/usr</filename> for example) then you
will need to use that file system mount point, and
not <filename>/usr/src</filename>.</para>
</warning>
</listitem>
<listitem>
<para>The file system holding
<filename>/usr/obj</filename> can be mounted (or
remounted) with the <option>async</option> option.
This causes disk writes to happen asynchronously.
In other words, the write completes immediately, and
the data is written to the disk a few seconds later.
This allows writes to be clustered together, and can
be a dramatic performance boost.</para>
<warning>
<para>Keep in mind that this option makes your file
system more fragile. With this option there is an
increased chance that, should power fail, the file
system will be in an unrecoverable state when the
machine restarts.</para>
<para>If <filename>/usr/obj</filename> is the only
thing on this file system then it is not a
problem. If you have other, valuable data on the
same file system then ensure your backups are
fresh before you enable this option.</para>
</warning>
<screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen>
<warning>
<para>As above, if <filename>/usr/obj</filename> is
not on its own file system, replace it in the
example with the name of the appropriate mount
point.</para>
</warning>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>What do I do if something goes wrong?</para>
</question>
<answer>
<para>Make absolutely sure your environment has no
extraneous cruft from earlier builds. This is simple
enough.</para>
<screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
&prompt.root; <userinput>rm -rf /usr/obj/usr</userinput>
&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make cleandir</userinput>
&prompt.root; <userinput>make cleandir</userinput></screen>
<para>Yes, <command>make cleandir</command> really should
be run twice.</para>
<para>Then restart the whole process, starting
with <command>make buildworld</command>.</para>
<para>If you still have problems, send the error and the
output of <command>uname -a</command> to &a.questions;.
Be prepared to answer other questions about your
setup!</para>
</answer>
</qandaentry>
</qandaset>
</sect2>
</sect1>
<sect1 id="make-delete-old">
<sect1info>
<authorgroup>
<author>
<firstname>Anton</firstname>
<surname>Shterenlikht</surname>
<contrib>Based on notes provided by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Deleting Obsolete Files, Directories and Libraries</title>
<indexterm>
<primary>Deleting obsolete files, directories and
libraries</primary>
</indexterm>
<para>As a part of the &os; development lifecycle, it happens from
time to time that files and their contents become obsolete.
This may be because their functionality is implemented
elsewhere, the version number of the library has changed or it
was removed from the system entirely. This includes old files,
libraries and directories, which should be removed when updating
the system. The benefit for the user is that the system is not
cluttered with old files which take up unnecessary space on the
storage (and backup) medium. Additionally, if the old library
had a security or stability issue, you should update to the
newer library to keep your system safe and prevent crashes
caused by the old library implementation. The files,
directories, and libraries that are considered obsolete are
listed in <filename>/usr/src/ObsoleteFiles.inc</filename>. The
following instructions will help you removing these obsolete
files during the system upgrade process.</para>
<para>We assume you are following the steps outlined in
<xref linkend="canonical-build"/>. After the
<command>make <maketarget>installworld</maketarget></command>
and the subsequent <command>mergemaster</command> commands have
finished successfully, you should check for obsolete files and
libraries as follows:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make check-old</userinput></screen>
<para>If any obsolete files are found, they can be deleted using
the following commands:</para>
<screen>&prompt.root; <userinput>make delete-old</userinput></screen>
<tip>
<para>See <filename>/usr/src/Makefile</filename>
for more targets of interest.</para>
</tip>
<para>A prompt is displayed before deleting each obsolete file.
You can skip the prompt and let the system remove these files
automatically by using the
<makevar>BATCH_DELETE_OLD_FILES</makevar> make-variable as
follows:</para>
<screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
<para>You can also achieve the same goal by piping these commands
through <command>yes</command> like this:</para>
<screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
<warning>
<title>Warning</title>
<para>Deleting obsolete files will break applications that
still depend on those obsolete files. This is especially true
for old libraries. In most cases, you need to recompile the
programs, ports, or libraries that used the old library before
<command>make
<maketarget>delete-old-libs</maketarget></command> is
executed.</para>
</warning>
<para>Utilities for checking shared library dependencies are
available from the Ports Collection in
<filename role="package">sysutils/libchk</filename> or <filename
role="package">sysutils/bsdadminscripts</filename>.</para>
<para>Obsolete shared libraries can conflict with newer libraries,
causing messages like these:</para>
<screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
<para>To solve these problems, determine which port installed the
library:</para>
<screen>&prompt.root; <userinput>pkg_info -W /usr/local/lib/libtiff.so</userinput>
/usr/local/lib/libtiff.so was installed by package tiff-3.9.4
&prompt.root; <userinput>pkg_info -W /usr/local/lib/libXext.so</userinput>
/usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen>
<para>Then deinstall, rebuild and reinstall the port. The
<filename role="package">ports-mgmt/portmaster</filename> and
<filename role="package">ports-mgmt/portupgrade</filename>
utilities can be used to automate this process. After you have
made sure that all ports are rebuilt and do not use the old
libraries any more, you can delete them using the following
command:</para>
<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
</sect1>
<sect1 id="small-lan">
<sect1info>
<authorgroup>
<author>
<firstname>Mike</firstname>
<surname>Meyer</surname>
<contrib>Contributed by </contrib>
</author>
</authorgroup>
</sect1info>
<title>Tracking for Multiple Machines</title>
<indexterm>
<primary>NFS</primary>
<secondary>installing multiple machines</secondary>
</indexterm>
<para>If you have multiple machines that you want to track the
same source tree, then having all of them download sources and
rebuild everything seems like a waste of resources: disk space,
network bandwidth, and CPU cycles. It is, and the solution is
to have one machine do most of the work, while the rest of the
machines mount that work via NFS. This section outlines a
method of doing so.</para>
<sect2 id="small-lan-preliminaries">
<title>Preliminaries</title>
<para>First, identify a set of machines that is going to run
the same set of binaries, which we will call a
<emphasis>build set</emphasis>. Each machine can have a
custom kernel, but they will be running the same userland
binaries. From that set, choose a machine to be the
<emphasis>build machine</emphasis>. It is going to be the
machine that the world and kernel are built on. Ideally, it
should be a fast machine that has sufficient spare CPU to run
<command>make buildworld</command> and
<command>make buildkernel</command>. You will also want to
choose a machine to be the <emphasis>test machine</emphasis>,
which will test software updates before they are put into
production. This <emphasis>must</emphasis> be a machine that
you can afford to have down for an extended period of time.
It can be the build machine, but need not be.</para>
<para>All the machines in this build set need to mount
<filename>/usr/obj</filename> and
<filename>/usr/src</filename> from the same machine, and at
the same point. Ideally, those are on two different drives on
the build machine, but they can be NFS mounted on that machine
as well. If you have multiple build sets,
<filename>/usr/src</filename> should be on one build machine,
and NFS mounted on the rest.</para>
<para>Finally make sure that
<filename>/etc/make.conf</filename> and
<filename>/etc/src.conf</filename> on all the machines in the
build set agrees with the build machine. That means that the
build machine must build all the parts of the base system that
any machine in the build set is going to install. Also, each
build machine should have its kernel name set with
<makevar>KERNCONF</makevar> in
<filename>/etc/make.conf</filename>, and the build machine
should list them all in <makevar>KERNCONF</makevar>, listing
its own kernel first. The build machine must have the kernel
configuration files for each machine in
<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>
if it is going to build their kernels.</para>
</sect2>
<sect2 id="small-lan-base-system">
<title>The Base System</title>
<para>Now that all that is done, you are ready to build
everything. Build the kernel and world as described in
<xref linkend="make-buildworld"/> on the build machine, but do
not install anything. After the build has finished, go to the
test machine, and install the kernel you just built. If this
machine mounts <filename>/usr/src</filename> and
<filename>/usr/obj</filename> via NFS, when you reboot to
single user you will need to enable the network and mount
them. The easiest way to do this is to boot to multi-user,
then run <command>shutdown now</command> to go to single user
mode. Once there, you can install the new kernel and world
and run <command>mergemaster</command> just as you normally
would. When done, reboot to return to normal multi-user
operations for this machine.</para>
<para>After you are certain that everything on the test
machine is working properly, use the same procedure to
install the new software on each of the other machines in
the build set.</para>
</sect2>
<sect2 id="small-lan-ports">
<title>Ports</title>
<para>The same ideas can be used for the ports tree. The first
critical step is mounting <filename>/usr/ports</filename> from
the same machine to all the machines in the build set. You
can then set up <filename>/etc/make.conf</filename> properly
to share distfiles. You should set <makevar>DISTDIR</makevar>
to a common shared directory that is writable by whichever
user <username>root</username> is mapped to by your NFS
mounts. Each machine should set
<makevar>WRKDIRPREFIX</makevar> to a local build directory.
Finally, if you are going to be building and distributing
packages, you should set <makevar>PACKAGES</makevar> to a
directory similar to <makevar>DISTDIR</makevar>.</para>
</sect2>
</sect1>
</chapter>