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

All the required steps are now in order, in one place, and in a Procedure.

Browse source 
Next round will improve the flow of the next subsection.
Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne 2014-02-06 01:40:32 +00:00
parent 5925aef841
commit 7843d93cf1
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=43796
1 changed files with 88 additions and 145 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -1500,11 +1500,11 @@ before running "/usr/sbin/freebsd-update install"</screen>
<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 install"</screen>
<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 install"</screen>
<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>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
<buildtarget>installworld</buildtarget> step will be able
to use the newly installed system user or system group
names without problems.</para>
</step>
<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>
</step>
<step>
<para><command>mergemaster</command></para>
<para>Repeated to update the remaining configuration files,
now that the new world is on disk.</para>
</step>
<step>
<para><command>make
delete-old</command></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>
</step>
<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>
</step>
<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>
</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>
<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>If using ZFS(assuming a zpool name of zroot), run:</para>
<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>
<para>Then run:</para>
<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 new system accounts and groups.</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>
<screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
</step>
<warning>
<title>Read Further Explanations</title>
<step>
<para>Install the new world
from <filename class="directory">/usr/obj</filename>.</para>
<para>The following sections clearly describe each step,
especially when using a custom kernel configuration.</para>
</warning>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput></screen>
</step>
<step>
<para>Update any remaining configuration files.</para>
<screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
</step>
<step>
<para>Delete any obsolete files. This is
important as they may cause problems if left on
the disk.</para>
<screen>&prompt.root; <userinput>make delete-old</userinput></screen>
</step>
<step>
<para>A full reboot is now needed to load the new
kernel and new world with the new configuration files.</para>
<screen>&prompt.root; <userinput>reboot</userinput></screen>
</step>
<step>
<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>
<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
</step>
</procedure>
</sect2>
<sect2 xml:id="src-updating">
@ -1709,6 +1650,8 @@ before running "/usr/sbin/freebsd-update install"</screen>
<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