svn commit: r43796 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Dru Lavigne
dru at FreeBSD.org
Thu Feb 6 01:40:33 UTC 2014
Author: dru
Date: Thu Feb 6 01:40:32 2014
New Revision: 43796
URL: http://svnweb.freebsd.org/changeset/doc/43796
Log:
All the required steps are now in order, in one place, and in a Procedure.
Next round will improve the flow of the next subsection.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu Feb 6 00:22:35 2014 (r43795)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu Feb 6 01:40:32 2014 (r43796)
@@ -1500,11 +1500,11 @@ before running "/usr/sbin/freebsd-update
<title>Overview of Process</title>
<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
+ version using the source of a newer
+ version that was obtained using the instructions in
<xref linkend="synching"/>.</para>
- <para><quote>World</quote> includes the &os; kernel, core system binaries,
+ <para>In &os;, the term <quote>world</quote> includes the kernel, core system binaries,
libraries, programming files, and built-in compiler. The order in which these
components are built and installed is important.</para>
@@ -1522,13 +1522,13 @@ before running "/usr/sbin/freebsd-update
<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. 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.</para>
+ used. For the most part, the update process only replaces or
+ adds files and existing old files are not deleted. Since
+ this can cause problems, <filename>/usr/src/UPDATING</filename>
+ will indicate if any files
+ need to be manually deleted and at which step to do so.</para>
- <para>These concerns have led to the following recommended upgrade
+ <para>These concerns have led to the recommended upgrade
sequence described in
the following procedure.</para>
@@ -1537,169 +1537,110 @@ before running "/usr/sbin/freebsd-update
<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>
-
- <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>/usr/obj</filename>.</para>
+
+ <step>
+ <para>Compile the new compiler and a few related
+ tools, then use the new compiler to compile the rest of
+ the new world. The result is saved to
+ <filename class="directory">/usr/obj</filename>.</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make buildworld</userinput></screen>
</step>
<step>
- <para><command>make
- buildkernel</command></para>
+ <para>Use the new compiler
+ residing in <filename class="directory">/usr/obj</filename>
+ to build the new kernel, in order to
+ protect against compiler-kernel mismatches:</para>
- <para>This uses the <emphasis>new</emphasis> compiler
- residing in <filename>/usr/obj</filename> in order to
- protect against compiler-kernel mismatches.</para>
+ <screen>&prompt.root; <userinput>make buildkernel</userinput></screen>
</step>
<step>
- <para><command>make
- installkernel</command></para>
-
- <para>Place the new kernel and kernel modules onto the disk,
+ <para>Install the new kernel and kernel modules,
making it possible to boot with the newly updated
- kernel.</para>
+ kernel:</para>
+
+ <screen>&prompt.root; <userinput>make installkernel</userinput></screen>
</step>
<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
+ <para>Drop the system into single user mode in order to minimize problems from updating
+ any binaries that are already running. It also minimizes any
problems from running the old world on a new
kernel.</para>
- </step>
- <step>
- <para><command>mergemaster
- -p</command></para>
+ <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
+
+ <para>Once in single-user mode, run this command if the
+ system is formatted with UFS:</para>
+
+ <screen>&prompt.root; <userinput>mount -u /</userinput>
+&prompt.root; <userinput>mount -a -t ufs</userinput></screen>
- <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
+ <para>If the system is instead formatted with ZFS, run these
+ two commands. This example assumes a zpool name of <literal>zroot</literal>:</para>
+
+ <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput>
+&prompt.root; <userinput>zfs mount -a</userinput></screen>
+ </step>
+
+ <step>
+ <para>Then, for either filesystem, run:</para>
+ <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
+ </step>
+
+ <step>
+ <para>Next, perform some initial configuration file updates in
+ preparation for the new world. For instance, this step may add
+ new groups or new system accounts which have been added
+ to &os; since the last update. This is necessary so that the
<buildtarget>installworld</buildtarget> step will be able
- to use the newly installed system user or system group
- names without problems.</para>
+ to use the new system accounts and groups.</para>
+
+ <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
</step>
<step>
- <para><command>make
- installworld</command></para>
+ <para>Install the new world
+ from <filename class="directory">/usr/obj</filename>.</para>
- <para>Copies the world
- from <filename>/usr/obj</filename>. The
- new kernel and new world are now installed on disk.</para>
+ <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make installworld</userinput></screen>
</step>
<step>
- <para><command>mergemaster</command></para>
+ <para>Update any remaining configuration files.</para>
- <para>Repeated to update the remaining configuration files,
- now that the new world is on disk.</para>
+ <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
</step>
<step>
- <para><command>make
- delete-old</command></para>
+ <para>Delete any obsolete files. This is
+ important as they may cause problems if left on
+ the disk.</para>
- <para>This target deletes old (obsolete) files. This is
- important because sometimes they cause problems if left on
- the disk, for example the presence of the old
- <filename>utmp.h</filename> causes problems in some ports
- when the new <filename>utmpx.h</filename> is
- installed.</para>
+ <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
</step>
<step>
- <para>Reboot.</para>
+ <para>A full reboot is now needed to load the new
+ kernel and new world with the new configuration files.</para>
- <para>A full machine reboot is needed now to load the new
- kernel and new world with new configuration files.</para>
+ <screen>&prompt.root; <userinput>reboot</userinput></screen>
</step>
<step>
- <para><command>make
- delete-old-libs</command></para>
+ <para>Make sure that all installed ports have first been rebuilt
+ before old libraries are removed using the instructions in
+ <xref linkend="ports-upgrading"/>. When finished,
+ remove any obsolete libraries to avoid conflicts with
+ newer ones.</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>
+ <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
</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
- 9.1, may not need this procedure since it is less likely to
- run into serious mismatches between compiler, kernel,
- userland, and configuration files. The approach of
- <command>make world</command>
- followed by building and installing a new kernel might work
- well enough for minor updates.</para>
-
- <para>When upgrading across major releases, people who do not
- follow this procedure should expect some problems.</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
- <buildtarget>buildworld</buildtarget> step. These are
- described in <filename>UPDATING</filename>. In general,
- though, this step can safely be omitted when not updating
- across one or more major &os; versions.</para>
- </note>
-
- <para>After <buildtarget>installkernel</buildtarget> finishes
- successfully, boot into single user mode using <command>boot
- -s</command> from the loader prompt.</para>
-
- <para>If using UFS, run:</para>
-
- <screen>&prompt.root; <userinput>mount -u /</userinput>
-&prompt.root; <userinput>mount -a -t ufs</userinput></screen>
-
- <para>If using ZFS(assuming a zpool name of zroot), run:</para>
-
- <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput>
-&prompt.root; <userinput>zfs mount -a</userinput></screen>
-
- <para>Then run:</para>
-
- <screen>&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>make delete-old</userinput>
-&prompt.root; <userinput>reboot</userinput>
-&prompt.root; <userinput>make delete-old-libs</userinput></screen>
-
- <warning>
- <title>Read Further Explanations</title>
-
- <para>The following sections clearly describe each step,
- especially when using a custom kernel configuration.</para>
- </warning>
</sect2>
<sect2 xml:id="src-updating">
@@ -1709,6 +1650,8 @@ before running "/usr/sbin/freebsd-update
<primary><filename>make.conf</filename></primary>
</indexterm>
+ <para>The following sections clearly describe each step,
+ especially when using a custom kernel configuration.</para>
<para>Available &man.make.1; options are shown in
&man.make.conf.5; and
<filename>/usr/share/examples/etc/make.conf</filename>. These
More information about the svn-doc-head
mailing list