svn commit: r43794 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Dru Lavigne
dru at FreeBSD.org
Wed Feb 5 23:11:37 UTC 2014
Author: dru
Date: Wed Feb 5 23:11:36 2014
New Revision: 43794
URL: http://svnweb.freebsd.org/changeset/doc/43794
Log:
Initial shuffle in this section, much more to come in order to improve its flow.
Place pre-build tasks at beginning and format as a procedure.
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 Wed Feb 5 20:59:58 2014 (r43793)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Wed Feb 5 23:11:36 2014 (r43794)
@@ -1437,46 +1437,53 @@ before running "/usr/sbin/freebsd-update
</indexterm>
<para>Once the local source tree is synchronized against a
particular version of &os; such as &os.stable; or &os.current;,
- the source tree can be used to rebuild the system.</para>
-
- <warning>
- <title>Make a Backup</title>
-
- <para>It cannot be stressed enough how important it is to make a
+ the source tree can be used to rebuild the system. This process
+ is known as rebuilding world.</para>
+
+ <para><emphasis>Before</emphasis> rebuilding world, be sure to
+ perform the following tasks:</para>
+
+ <procedure>
+ <title>Perform These Tasks Before Building World</title>
+
+ <step>
+ <para>Backup all important data to another system or removable
+ media, verify the integrity of the backup, and have a bootable
+ installation media at hand. It cannot be
+ stressed enough how important it is to make a
backup of the system <emphasis>before</emphasis> rebuilding
- the system. While rebuilding the world is an easy task, there
+ the system. While rebuilding world is an easy task, there
will inevitably be times when mistakes in the source tree
- render the system unbootable.</para>
-
- <para>Create and verify a backup and have a bootable
- installation media at hand. You will probably never have
- to use it, but it is better to be safe than sorry!</para>
- </warning>
-
- <warning>
- <title>Subscribe to the Right Mailing List</title>
+ render the system unbootable. You will probably never have
+ to use the backup, but it is better to be safe than sorry!</para>
+ </step>
+ <step>
<indexterm><primary>mailing list</primary></indexterm>
- <para>The &os.stable; and &os.current; branches are, by their
- nature, <emphasis>in development</emphasis>. People that
- contribute to &os; are human, and mistakes occasionally
- happen.</para>
-
- <para>Sometimes these mistakes can be quite harmless, just
- causing the system to print a new diagnostic warning. Or the
- change may be catastrophic, and render the system unbootable
- or destroy file systems.</para>
-
- <para>When problems occur, a <quote>heads up</quote> is
- posted to the appropriate mailing list, explaining the nature
- of the problem and which systems it affects. An <quote>all
- clear</quote> announcement is posted when the problem has
- been solved.</para>
-
- <para>Users who track &os.stable; or &os.current; and do
- not read &a.stable; or &a.current; respectively, are asking
- for trouble.</para>
- </warning>
+ <para>Review the recent &a.stable.name; or &a.current.name; entries, depending
+ upon the branch being tracked. Be aware of any known
+ problems and which systems are affected. If a known issue
+ affects the version of synchronized code, wait for an <quote>all
+ clear</quote> announcement to be posted stating that the problem has
+ been solved. Resynchronize the sources to ensure that the
+ local version of source has the needed fix.</para>
+ </step>
+
+ <step>
+ <para>Read
+ <filename>/usr/src/UPDATING</filename> for any pre-buildworld
+ steps necessary for that version of the source. This file contains
+ important information about potential problems and may specify
+ the order to run certain commands. Many upgrades require
+ specific additional steps such as renaming or deleting
+ specific files prior to installworld. These will be listed
+ at the end of this file where the currently recommended upgrade sequence
+ is explicitly spelled out. If
+ <filename>UPDATING</filename> contradicts any steps in
+ this chapter, the instructions in <filename>UPDATING</filename> take
+ precedence and should be followed.</para>
+ </step>
+ </procedure>
<warning>
<title>Do Not Use <command>make world</command></title>
@@ -1492,10 +1499,8 @@ before running "/usr/sbin/freebsd-update
<sect2 xml:id="canonical-build">
<title>The Canonical Way to Update Your System</title>
- <para>Before updating the system, read
- <filename>/usr/src/UPDATING</filename> for any pre-buildworld
- steps necessary for that version of the sources. Then, use
- the procedure outlined here.</para>
+ <para>Once the above tasks have been performed, use
+ the procedure outlined here to update the system.</para>
<para>These upgrade steps assume an upgrade from an older &os;
version, consisting of an old compiler, old kernel,
@@ -1685,13 +1690,6 @@ before running "/usr/sbin/freebsd-update
<para>When upgrading across major releases, people who do not
follow this procedure should expect some problems.</para>
- <para>It is also worth noting that many upgrades may require
- specific additional steps such as renaming or deleting
- specific files prior to installworld. Read
- <filename>/usr/src/UPDATING</filename> 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
@@ -1749,25 +1747,6 @@ before running "/usr/sbin/freebsd-update
</sect2>
<sect2 xml:id="src-updating">
- <title>Read <filename>/usr/src/UPDATING</filename></title>
-
- <para>Before updating, read
- <filename>/usr/src/UPDATING</filename>. This file contains
- important information about potential problems and may specify
- the order to run certain commands. If
- <filename>UPDATING</filename> contradicts the procedure in
- this section, <filename>UPDATING</filename> takes
- precedence.</para>
-
- <important>
- <para>Reading <filename>UPDATING</filename> is not an
- acceptable substitute for subscribing to the correct mailing
- list. The two requirements are complementary, not
- exclusive.</para>
- </important>
- </sect2>
-
- <sect2 xml:id="make-conf">
<title>Check <filename>/etc/make.conf</filename></title>
<indexterm>
@@ -1917,12 +1896,9 @@ before running "/usr/sbin/freebsd-update
&prompt.root; <userinput>rm -rf *</userinput></screen>
</sect2>
- <sect2 xml:id="updating-upgrading-compilebase">
+ <sect2 xml:id="make-buildworld">
<title>Recompile the Base System</title>
- <sect3>
- <title>Saving the Output</title>
-
<para>It is a good idea to save the output from running
&man.make.1; to a file. If something goes wrong, a copy of
the error message can be posted to one of the &os; mailing
@@ -1948,10 +1924,6 @@ Script done, …</screen>
<filename>/var/tmp</filename> or in
<systemitem class="username">root</systemitem>'s home
directory.</para>
- </sect3>
-
- <sect3 xml:id="make-buildworld">
- <title>Compile the Base System</title>
<para>While in <filename>/usr/src</filename>
type:</para>
@@ -2068,10 +2040,6 @@ Script done, …</screen>
<para>On a multi-CPU machine using an SMP configured kernel,
try values between 6 and 10 and see how they speed things
up.</para>
- </sect3>
-
- <sect3>
- <title>Timings</title>
<indexterm>
<primary>rebuilding <quote>world</quote></primary>
@@ -2083,7 +2051,6 @@ Script done, …</screen>
&os.stable; tree, with no tricks or shortcuts used during
the process. A &os.current; tree will take somewhat
longer.</para>
- </sect3>
</sect2>
<sect2 xml:id="new-kernel">
More information about the svn-doc-all
mailing list