From owner-svn-doc-head@FreeBSD.ORG Thu Feb 6 00:22:36 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 24E226E5; Thu, 6 Feb 2014 00:22:36 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 0D3A21B5A; Thu, 6 Feb 2014 00:22:36 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s160MZdK026508; Thu, 6 Feb 2014 00:22:35 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s160MZZa026507; Thu, 6 Feb 2014 00:22:35 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201402060022.s160MZZa026507@svn.freebsd.org> From: Dru Lavigne Date: Thu, 6 Feb 2014 00:22:35 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 06 Feb 2014 00:22:36 -0000 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: - Perform These Tasks Before Building World + Perform These Tasks <emphasis>Before</emphasis> Building World Backup all important data to another system or removable @@ -1497,91 +1497,47 @@ before running "/usr/sbin/freebsd-update - The Canonical Way to Update Your System + Overview of Process - Once the above tasks have been performed, use - the procedure outlined here to update the system. - - These upgrade steps assume an upgrade from an older &os; - version, consisting of an old compiler, old kernel, - old world, and old configuration files. - World includes the core system binaries, - libraries, and programming files. The compiler is part of - world, but has a few special concerns. - - 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 for detailed - help about synchronizing to a newer version. - - 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. - - Any successful update sequence must deal with the - following issues: - - - - 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 - installed before building the new - kernel. - - - - The new world might rely on new kernel features. So, - the new kernel must be installed before the new world is - installed. - - - - These first two issues are the basis for the - core buildworld, - buildkernel, - installkernel, - installworld sequence described in - the following paragraphs. Other reasons for using these - steps are listed below: - - - - The old world might not run correctly on the new + 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 + . + + World 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. + + 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. + + 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. - - 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 + 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. - - - - 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: + should be manually deleted at certain steps. + + These concerns have led to the following recommended upgrade + sequence described in + the following procedure. - - + + Overview of Build World Process + + 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 @@ -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 /usr/obj. - + - + make buildkernel This uses the new compiler residing in /usr/obj in order to protect against compiler-kernel mismatches. - + - + make installkernel Place the new kernel and kernel modules onto the disk, making it possible to boot with the newly updated kernel. - + - + Reboot into single user mode. 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. - + - + mergemaster -p @@ -1631,25 +1587,25 @@ before running "/usr/sbin/freebsd-update 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 @@ -1659,24 +1615,24 @@ before running "/usr/sbin/freebsd-update 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