os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

More shuffling to improve the flow. Still a WIP with much more to come.

Browse source 
Format the build world process as a Procedure.

Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne 2014-02-06 00:22:35 +00:00
parent cae6bd8f51
commit 5925aef841
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=43795
1 changed files with 49 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

142
en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
View file

@ -1444,7 +1444,7 @@ before running "/usr/sbin/freebsd-update install"</screen>
perform the following tasks:</para>
<procedure>
<title>Perform These Tasks Before Building World</title>
<title>Perform These Tasks <emphasis>Before</emphasis> Building World</title>
<step>
<para>Backup all important data to another system or removable
@ -1497,91 +1497,47 @@ before running "/usr/sbin/freebsd-update install"</screen>
</warning>
<sect2 xml:id="canonical-build">
<title>The Canonical Way to Update Your System</title>
<title>Overview of Process</title>
<para>Once the above tasks have been performed, use
the procedure outlined here to update the system.</para>
<para>The build world process assumes an upgrade from an older &os;
version using the sources to a newer
version that were obtained using the instructions in
<xref linkend="synching"/>.</para>
<para><quote>World</quote> includes the &os; kernel, core system binaries,
libraries, programming files, and built-in compiler. The order in which these
components are built and installed is important.</para>
<para>For example, the old compiler might have a bug and not be able to
compile the new kernel. Since the new kernel should be
built with the new compiler, the new compiler
must be built, but not necessarily installed, before the new kernel is built.</para>
<para>These upgrade steps assume an upgrade from an older &os;
version, consisting of an old compiler, old kernel,
old world, and old configuration files.
<quote>World</quote> includes the core system binaries,
libraries, and programming files. The compiler is part of
<quote>world</quote>, but has a few special concerns.</para>
<para>These steps also assume that the sources to a newer
version have already been obtained. If the sources are not
up-to-date, refer to <xref linkend="synching"/> for detailed
help about synchronizing to a newer version.</para>
<para>Updating the system from source is a more subtle process
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 have a bug and not be able to
compile the new kernel. So, the new kernel should be
built with the new compiler, meaning that 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 <buildtarget>buildworld</buildtarget>,
<buildtarget>buildkernel</buildtarget>,
<buildtarget>installkernel</buildtarget>,
<buildtarget>installworld</buildtarget> sequence described in
the following paragraphs. Other reasons for using these
steps are listed below:</para>
<itemizedlist>
<listitem>
<para>The old world might not run correctly on the new
<para>The new world might rely on new kernel features,
so the new kernel must be installed before the new world is
installed. The old world might not run correctly on the new
kernel, so the new world must be installed immediately
upon installing the new kernel.</para>
</listitem>
<listitem>
<para>Some configuration changes must be made before the new
world is installed, but others might break the old world.
Hence, two different configuration upgrade steps are
generally needed.</para>
</listitem>
<listitem>
<para>For the most part, the update process only replaces or
generally needed. For the most part, the update process only replaces or
adds files and 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>
should be manually deleted at certain steps.</para>
<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>
<para>These concerns have led to the following recommended upgrade
sequence described in
the following procedure.</para>
<orderedlist>
<listitem>
<procedure>
<title>Overview of Build World Process</title>
<para>The commands used in the build world process should be run in the order specified
here. This section summarizes the function of each command.</para>
<step>
<para><command>make
buildworld</command></para>
@ -1589,36 +1545,36 @@ before running "/usr/sbin/freebsd-update install"</screen>
tools, then uses the new compiler to compile the rest of
the new world. The result ends up in
<filename>/usr/obj</filename>.</para>
</listitem>
</step>
<listitem>
<step>
<para><command>make
buildkernel</command></para>
<para>This uses the <emphasis>new</emphasis> compiler
residing in <filename>/usr/obj</filename> in order to
protect against compiler-kernel mismatches.</para>
</listitem>
</step>
<listitem>
<step>
<para><command>make
installkernel</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>
</step>
<listitem>
<step>
<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>
</step>
<listitem>
<step>
<para><command>mergemaster
-p</command></para>
@ -1631,25 +1587,25 @@ before running "/usr/sbin/freebsd-update install"</screen>
<buildtarget>installworld</buildtarget> step will be able
to use the newly installed system user or system group
names without problems.</para>
</listitem>
</step>
<listitem>
<step>
<para><command>make
installworld</command></para>
<para>Copies the world
from <filename>/usr/obj</filename>. The
new kernel and new world are now installed on disk.</para>
</listitem>
</step>
<listitem>
<step>
<para><command>mergemaster</command></para>
<para>Repeated to update the remaining configuration files,
now that the new world is on disk.</para>
</listitem>
</step>
<listitem>
<step>
<para><command>make
delete-old</command></para>
@ -1659,24 +1615,24 @@ before running "/usr/sbin/freebsd-update install"</screen>
<filename>utmp.h</filename> causes problems in some ports
when the new <filename>utmpx.h</filename> is
installed.</para>
</listitem>
</step>
<listitem>
<step>
<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>
</step>
<listitem>
<step>
<para><command>make
delete-old-libs</command></para>
<para>Remove any obsolete libraries to avoid conflicts with
newer ones. Make sure that all ports have been rebuilt
before old libraries are removed.</para>
</listitem>
</orderedlist>
</step>
</procedure>
<para>Upgrades from one release of the same &os; branch to a
more recent release of the same branch, such as from 9.0 to