Date: Wed, 5 Feb 2014 23:11:36 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43794 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201402052311.s15NBaiI096561@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402052311.s15NBaiI096561>