Add an explanation of the reasons that buildworld, buildkernel,
installkernel, reboot, ... is a good idea. Before describing every step in detail, we let the reader know "why" so that they can later appreciate the "how" a bit more, and feel less confused about the whole dance. PR: docs/43941 Submitted by: kientzle Reviewed by: trhodes
This commit is contained in:
Giorgos Keramidas
parent
349bba8633
commit
52ee421a00
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=33789
1 changed files with 184 additions and 3 deletions
|
|
@ -1588,9 +1588,190 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
|
|||
<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 following
|
||||
procedure:</para>
|
||||
<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's 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're 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're 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 don't
|
||||
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>
|
||||
|
||||
<note>
|
||||
<para>Upgrading from &os; 3.<replaceable>X</replaceable> or earlier
|
||||
releases is a bit trickier; read <filename>UPDATING</filename>
|
||||
carefully if you have to perform this sort of upgrade.</para>
|
||||
</note>
|
||||
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue