diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
index e4f2f14ccb..563d441cf8 100644
--- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
@@ -1500,11 +1500,11 @@ before running "/usr/sbin/freebsd-update install"
Overview of Process
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
.
- World
includes the &os; kernel, core system binaries,
+ In &os;, the term world
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.
@@ -1522,13 +1522,13 @@ before running "/usr/sbin/freebsd-update install"
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.
+ 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, /usr/src/UPDATING
+ will indicate if any files
+ need to be manually deleted and at which step to do so.
- These concerns have led to the following recommended upgrade
+ These concerns have led to the recommended upgrade
sequence described in
the following procedure.
@@ -1537,169 +1537,110 @@ before running "/usr/sbin/freebsd-update install"
The commands used in the build world process should be run in the order specified
here. This section summarizes the function of each command.
-
- make
- buildworld
- 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
- /usr/obj.
+
+ 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
+ /usr/obj.
+
+ &prompt.root; cd /usr/src
+&prompt.root; make buildworld
- make
- buildkernel
+ Use the new compiler
+ residing in /usr/obj
+ to build the new kernel, in order to
+ protect against compiler-kernel mismatches:
- This uses the new compiler
- residing in /usr/obj in order to
- protect against compiler-kernel mismatches.
+ &prompt.root; make buildkernel
- make
- installkernel
-
- Place the new kernel and kernel modules onto the disk,
+ Install the new kernel and kernel modules,
making it possible to boot with the newly updated
- kernel.
+ kernel:
+
+ &prompt.root; make installkernel
- Reboot into single user mode.
-
- Single user mode minimizes problems from updating
- software that is already running. It also minimizes any
+ 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.
-
-
- mergemaster
- -p
+ &prompt.root; shutdown now
- 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
- installworld step will be able
- to use the newly installed system user or system group
- names without problems.
-
-
-
- make
- installworld
-
- Copies the world
- from /usr/obj. The
- new kernel and new world are now installed on disk.
-
-
-
- mergemaster
-
- Repeated to update the remaining configuration files,
- now that the new world is on disk.
-
-
-
- make
- delete-old
-
- 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
- utmp.h causes problems in some ports
- when the new utmpx.h is
- installed.
-
-
-
- Reboot.
-
- A full machine reboot is needed now to load the new
- kernel and new world with new configuration files.
-
-
-
- make
- delete-old-libs
-
- Remove any obsolete libraries to avoid conflicts with
- newer ones. Make sure that all ports have been rebuilt
- before old libraries are removed.
-
-
-
- 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
- make world
- followed by building and installing a new kernel might work
- well enough for minor updates.
-
- When upgrading across major releases, people who do not
- follow this procedure should expect some problems.
-
- 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.
-
- To summarize, the currently recommended way of upgrading
- &os; from sources is:
-
- &prompt.root; cd /usr/src
-&prompt.root; make buildworld
-&prompt.root; make buildkernel
-&prompt.root; make installkernel
-&prompt.root; shutdown -r now
-
-
- There are a few rare cases when an extra run of
- mergemaster -p is needed before the
- buildworld step. These are
- described in UPDATING. In general,
- though, this step can safely be omitted when not updating
- across one or more major &os; versions.
-
-
- After installkernel finishes
- successfully, boot into single user mode using boot
- -s from the loader prompt.
-
- If using UFS, run:
+ Once in single-user mode, run this command if the
+ system is formatted with UFS:
&prompt.root; mount -u /
&prompt.root; mount -a -t ufs
- If using ZFS(assuming a zpool name of zroot), run:
+ If the system is instead formatted with ZFS, run these
+ two commands. This example assumes a zpool name of zroot:
&prompt.root; zfs set readonly=off zroot
&prompt.root; zfs mount -a
+
- Then run:
+
+ Then, for either filesystem, run:
+ &prompt.root; adjkerntz -i
+
+
+
+ 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
+ installworld step will be able
+ to use the new system accounts and groups.
- &prompt.root; adjkerntz -i
-&prompt.root; mergemaster -p
-&prompt.root; cd /usr/src
-&prompt.root; make installworld
-&prompt.root; mergemaster
-&prompt.root; make delete-old
-&prompt.root; reboot
-&prompt.root; make delete-old-libs
+ &prompt.root; mergemaster -p
+
-
- Read Further Explanations
+
+ Install the new world
+ from /usr/obj.
- The following sections clearly describe each step,
- especially when using a custom kernel configuration.
-
+ &prompt.root; cd /usr/src
+&prompt.root; make installworld
+
+
+
+ Update any remaining configuration files.
+
+ &prompt.root; mergemaster -p
+
+
+
+ Delete any obsolete files. This is
+ important as they may cause problems if left on
+ the disk.
+
+ &prompt.root; make delete-old
+
+
+
+ A full reboot is now needed to load the new
+ kernel and new world with the new configuration files.
+
+ &prompt.root; reboot
+
+
+
+ Make sure that all installed ports have first been rebuilt
+ before old libraries are removed using the instructions in
+ . When finished,
+ remove any obsolete libraries to avoid conflicts with
+ newer ones.
+
+ &prompt.root; make delete-old-libs
+
+
@@ -1709,6 +1650,8 @@ before running "/usr/sbin/freebsd-update install"
make.conf
+ The following sections clearly describe each step,
+ especially when using a custom kernel configuration.
Available &man.make.1; options are shown in
&man.make.conf.5; and
/usr/share/examples/etc/make.conf. These