From owner-svn-doc-all@FreeBSD.ORG Thu Feb 6 01:40:33 2014 Return-Path: Delivered-To: svn-doc-all@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 13C0AA86; Thu, 6 Feb 2014 01:40:33 +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 F03F711E2; Thu, 6 Feb 2014 01:40:32 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s161eWRK056369; Thu, 6 Feb 2014 01:40:32 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s161eWrk056368; Thu, 6 Feb 2014 01:40:32 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201402060140.s161eWrk056368@svn.freebsd.org> From: Dru Lavigne Date: Thu, 6 Feb 2014 01:40:32 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43796 - 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-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 06 Feb 2014 01:40:33 -0000 Author: dru Date: Thu Feb 6 01:40:32 2014 New Revision: 43796 URL: http://svnweb.freebsd.org/changeset/doc/43796 Log: All the required steps are now in order, in one place, and in a Procedure. Next round will improve the flow of the next subsection. 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 Thu Feb 6 00:22:35 2014 (r43795) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu Feb 6 01:40:32 2014 (r43796) @@ -1500,11 +1500,11 @@ before running "/usr/sbin/freebsd-update Overview of Process 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 . - World includes the &os; kernel, core system binaries, + In &os;, the term world 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. @@ -1522,13 +1522,13 @@ before running "/usr/sbin/freebsd-update 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. + 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, /usr/src/UPDATING + will indicate if any files + need to be manually deleted and at which step to do so. - These concerns have led to the following recommended upgrade + These concerns have led to the recommended upgrade sequence described in the following procedure. @@ -1537,169 +1537,110 @@ before running "/usr/sbin/freebsd-update 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 - - 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 - /usr/obj. + + + 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 + /usr/obj. + + &prompt.root; cd /usr/src +&prompt.root; make buildworld - make - buildkernel + Use the new compiler + residing in /usr/obj + to build the new kernel, in order to + protect against compiler-kernel mismatches: - This uses the new compiler - residing in /usr/obj in order to - protect against compiler-kernel mismatches. + &prompt.root; make buildkernel - make - installkernel - - Place the new kernel and kernel modules onto the disk, + Install the new kernel and kernel modules, making it possible to boot with the newly updated - kernel. + kernel: + + &prompt.root; make installkernel - Reboot into single user mode. - - Single user mode minimizes problems from updating - software that is already running. It also minimizes any + 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. - - - mergemaster - -p + &prompt.root; shutdown now + + Once in single-user mode, run this command if the + system is formatted with UFS: + + &prompt.root; mount -u / +&prompt.root; mount -a -t ufs - 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 + If the system is instead formatted with ZFS, run these + two commands. This example assumes a zpool name of zroot: + + &prompt.root; zfs set readonly=off zroot +&prompt.root; zfs mount -a + + + + Then, for either filesystem, run: + &prompt.root; adjkerntz -i + + + + 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 installworld step will be able - to use the newly installed system user or system group - names without problems. + to use the new system accounts and groups. + + &prompt.root; mergemaster -p - make - installworld + Install the new world + from /usr/obj. - Copies the world - from /usr/obj. The - new kernel and new world are now installed on disk. + &prompt.root; cd /usr/src +&prompt.root; make installworld - mergemaster + Update any remaining configuration files. - Repeated to update the remaining configuration files, - now that the new world is on disk. + &prompt.root; mergemaster -p - make - delete-old + Delete any obsolete files. This is + important as they may cause problems if left on + the disk. - 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 - utmp.h causes problems in some ports - when the new utmpx.h is - installed. + &prompt.root; make delete-old - Reboot. + A full reboot is now needed to load the new + kernel and new world with the new configuration files. - A full machine reboot is needed now to load the new - kernel and new world with new configuration files. + &prompt.root; reboot - make - delete-old-libs + Make sure that all installed ports have first been rebuilt + before old libraries are removed using the instructions in + . When finished, + remove any obsolete libraries to avoid conflicts with + newer ones. - Remove any obsolete libraries to avoid conflicts with - newer ones. Make sure that all ports have been rebuilt - before old libraries are removed. + &prompt.root; make delete-old-libs - - 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 - make world - followed by building and installing a new kernel might work - well enough for minor updates. - - When upgrading across major releases, people who do not - follow this procedure should expect some problems. - - 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. - - To summarize, the currently recommended way of upgrading - &os; from sources is: - - &prompt.root; cd /usr/src -&prompt.root; make buildworld -&prompt.root; make buildkernel -&prompt.root; make installkernel -&prompt.root; shutdown -r now - - - There are a few rare cases when an extra run of - mergemaster -p is needed before the - buildworld step. These are - described in UPDATING. In general, - though, this step can safely be omitted when not updating - across one or more major &os; versions. - - - After installkernel finishes - successfully, boot into single user mode using boot - -s from the loader prompt. - - If using UFS, run: - - &prompt.root; mount -u / -&prompt.root; mount -a -t ufs - - If using ZFS(assuming a zpool name of zroot), run: - - &prompt.root; zfs set readonly=off zroot -&prompt.root; zfs mount -a - - Then run: - - &prompt.root; adjkerntz -i -&prompt.root; mergemaster -p -&prompt.root; cd /usr/src -&prompt.root; make installworld -&prompt.root; mergemaster -&prompt.root; make delete-old -&prompt.root; reboot -&prompt.root; make delete-old-libs - - - Read Further Explanations - - The following sections clearly describe each step, - especially when using a custom kernel configuration. - @@ -1709,6 +1650,8 @@ before running "/usr/sbin/freebsd-update make.conf + The following sections clearly describe each step, + especially when using a custom kernel configuration. Available &man.make.1; options are shown in &man.make.conf.5; and /usr/share/examples/etc/make.conf. These