Date: Thu, 6 Feb 2014 00:22:35 +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: r43795 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201402060022.s160MZZa026507@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Thu Feb 6 00:22:35 2014 New Revision: 43795 URL: http://svnweb.freebsd.org/changeset/doc/43795 Log: More shuffling to improve the flow. Still a WIP with much more to come. Format the build world process 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 23:11:36 2014 (r43794) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu Feb 6 00:22:35 2014 (r43795) @@ -1444,7 +1444,7 @@ before running "/usr/sbin/freebsd-update perform the following tasks:</para> <procedure> - <title>Perform These Tasks Before Building World</title> + <title>Perform These Tasks <emphasis>Before</emphasis> Building World</title> <step> <para>Backup all important data to another system or removable @@ -1497,91 +1497,47 @@ before running "/usr/sbin/freebsd-update </warning> <sect2 xml:id="canonical-build"> - <title>The Canonical Way to Update Your System</title> + <title>Overview of Process</title> - <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, - old world, and old configuration files. - <quote>World</quote> includes the core system binaries, - libraries, and programming files. The compiler is part of - <quote>world</quote>, but has a few special concerns.</para> - - <para>These steps also assume that the sources to a newer - version have already been obtained. If the sources are not - up-to-date, refer to <xref linkend="synching"/> for detailed - help about synchronizing to a newer version.</para> - - <para>Updating the system from source is a more subtle process - than it might initially seem to be, and the &os; developers - have found it necessary over the years to change the - recommended approach fairly dramatically as new kinds of - unavoidable dependencies come to light. The rest of this - section describes the rationale behind the currently - recommended upgrade sequence.</para> - - <para>Any successful update sequence must deal with the - following issues:</para> - - <itemizedlist> - <listitem> - <para>The old compiler might have a bug and not be able to - compile the new kernel. So, the new kernel should be - built with the new compiler, meaning that the new compiler - must be built before the new kernel is built. This does - not necessarily mean that the new compiler must be - <emphasis>installed</emphasis> before building the new - kernel.</para> - </listitem> - - <listitem> - <para>The new world might rely on new kernel features. So, - the new kernel must be installed before the new world is - installed.</para> - </listitem> - </itemizedlist> - - <para>These first two issues are the basis for the - core <buildtarget>buildworld</buildtarget>, - <buildtarget>buildkernel</buildtarget>, - <buildtarget>installkernel</buildtarget>, - <buildtarget>installworld</buildtarget> sequence described in - the following paragraphs. Other reasons for using these - steps are listed below:</para> - - <itemizedlist> - <listitem> - <para>The old world might not run correctly on the new + <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 + <xref linkend="synching"/>.</para> + + <para><quote>World</quote> includes the &os; kernel, core system binaries, + libraries, programming files, and built-in compiler. The order in which these + components are built and installed is important.</para> + + <para>For example, the old compiler might have a bug and not be able to + compile the new kernel. Since the new kernel should be + built with the new compiler, the new compiler + must be built, but not necessarily installed, before the new kernel is built.</para> + + <para>The new world might rely on new kernel features, + so the new kernel must be installed before the new world is + installed. The old world might not run correctly on the new kernel, so the new world must be installed immediately upon installing the new kernel.</para> - </listitem> - <listitem> <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.</para> - </listitem> - - <listitem> - <para>For the most part, the update process only replaces or + 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. This may or - may not be automated in the future.</para> - </listitem> - </itemizedlist> - - <para>These concerns have led to the following recommended - sequence. Note that the detailed sequence for particular - updates may require additional steps, but this core process - should remain unchanged for some time:</para> + should be manually deleted at certain steps.</para> + + <para>These concerns have led to the following recommended upgrade + sequence described in + the following procedure.</para> - <orderedlist> - <listitem> + <procedure> + <title>Overview of Build World Process</title> + + <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> @@ -1589,36 +1545,36 @@ before running "/usr/sbin/freebsd-update tools, then uses the new compiler to compile the rest of the new world. The result ends up in <filename>/usr/obj</filename>.</para> - </listitem> + </step> - <listitem> + <step> <para><command>make buildkernel</command></para> <para>This uses the <emphasis>new</emphasis> compiler residing in <filename>/usr/obj</filename> in order to protect against compiler-kernel mismatches.</para> - </listitem> + </step> - <listitem> + <step> <para><command>make installkernel</command></para> <para>Place the new kernel and kernel modules onto the disk, making it possible to boot with the newly updated kernel.</para> - </listitem> + </step> - <listitem> + <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 problems from running the old world on a new kernel.</para> - </listitem> + </step> - <listitem> + <step> <para><command>mergemaster -p</command></para> @@ -1631,25 +1587,25 @@ before running "/usr/sbin/freebsd-update <buildtarget>installworld</buildtarget> step will be able to use the newly installed system user or system group names without problems.</para> - </listitem> + </step> - <listitem> + <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> - </listitem> + </step> - <listitem> + <step> <para><command>mergemaster</command></para> <para>Repeated to update the remaining configuration files, now that the new world is on disk.</para> - </listitem> + </step> - <listitem> + <step> <para><command>make delete-old</command></para> @@ -1659,24 +1615,24 @@ before running "/usr/sbin/freebsd-update <filename>utmp.h</filename> causes problems in some ports when the new <filename>utmpx.h</filename> is installed.</para> - </listitem> + </step> - <listitem> + <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> - </listitem> + </step> - <listitem> + <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> - </listitem> - </orderedlist> + </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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402060022.s160MZZa026507>