From owner-freebsd-doc Fri Oct 11 14: 0:16 2002 Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 7D76A37B404 for ; Fri, 11 Oct 2002 14:00:09 -0700 (PDT) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 3AF6043EA3 for ; Fri, 11 Oct 2002 14:00:08 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.12.6/8.12.6) with ESMTP id g9BL08Co009217 for ; Fri, 11 Oct 2002 14:00:08 -0700 (PDT) (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.12.6/8.12.6/Submit) id g9BL08xF009216; Fri, 11 Oct 2002 14:00:08 -0700 (PDT) Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 3C15F37B401 for ; Fri, 11 Oct 2002 13:55:16 -0700 (PDT) Received: from www.freebsd.org (www.freebsd.org [216.136.204.117]) by mx1.FreeBSD.org (Postfix) with ESMTP id D625C43E7B for ; Fri, 11 Oct 2002 13:55:15 -0700 (PDT) (envelope-from nobody@FreeBSD.org) Received: from www.freebsd.org (localhost [127.0.0.1]) by www.freebsd.org (8.12.6/8.12.6) with ESMTP id g9BKtF7R017732 for ; Fri, 11 Oct 2002 13:55:15 -0700 (PDT) (envelope-from nobody@www.freebsd.org) Received: (from nobody@localhost) by www.freebsd.org (8.12.6/8.12.6/Submit) id g9BKtFqQ017731; Fri, 11 Oct 2002 13:55:15 -0700 (PDT) Message-Id: <200210112055.g9BKtFqQ017731@www.freebsd.org> Date: Fri, 11 Oct 2002 13:55:15 -0700 (PDT) From: Tim Kientzle To: freebsd-gnats-submit@FreeBSD.org X-Send-Pr-Version: www-1.0 Subject: docs/43941: Rationale for Upgrade Sequence Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org >Number: 43941 >Category: docs >Synopsis: Rationale for Upgrade Sequence >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Fri Oct 11 14:00:07 PDT 2002 >Closed-Date: >Last-Modified: >Originator: Tim Kientzle >Release: >Organization: >Environment: >Description: Mark Linimon suggested that I "get this exact reasoning added to the official docs, it's the clearest explanation I've seen yet." This was in response to a posting I made to freebsd-stable explaining some of the rationale behind the buildworld/buildkernel/installkernel/installworld sequence. I've attached the text of my posting below. I hope you find it useful. >How-To-Repeat: >Fix: The following is an edited version of my post to FreeBSD-stable mailing list on 11 Oct, 2002, in response to a question about why the "old" build sequence was no longer considered sufficient: ------------------------------------------ Problem: You're currently running an old system, consisting of old compiler, old kernel, old world, and old configuration files. (By "world" here, I mean the core system binaries, libraries, and programming files. The compiler is part of "world", but has a few special concerns, which is why I've named it separately here.) You have source code for a new system and want to compile and install it over the old system. How should this be done? This problem is a bit more subtle than it might seem, and the FreeBSD 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 following describes the rationale behind the current update sequence (being used by 5.0, for example). Any successful update sequence must deal with the following issues: * The old compiler might not be able to compile the new kernel. (Old compilers sometimes have bugs.) So, the new kernel should be built with the new compiler. In particular, 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, however. * 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 that I'll describe in a moment. They are not the only concerns, however: * The old world might not run correctly on the new kernel, so you must install the new world immediately upon installing the new kernel. * Some configuration changes must be done 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; 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: 1) 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. 2) make buildkernel Unlike the older config/make approach, this uses the _new_ compiler residing in /usr/obj. This protects you against compiler/kernel mismatches. 3) make installkernel Place the new kernel and kernel modules onto the disk. 4) Reboot to single user mode. Single user mode minimizes problems from updating software that's already running. It also minimizes any problems from running the old world on a new kernel. (Curiously, when moving from 4.x to 5.0, you're still running the old kernel here, because the new kernel is in a different place and the boot loader hasn't been updated yet.) 5) mergemaster -p This does some initial configuration file updates in preparation for the new world. 6) make installworld Copies the world from /usr/obj. You now have a new kernel and new world on disk. 7) mergemaster Now you can update the remaining configuration files, since you have a new world on disk. 8) reboot A full machine reboot is needed now to load the new kernel and new world with new configuration files. Note that if you're upgrading from, say, 4.6.2 to 4.7, then this procedure may not be absolutely necessary, since you're unlikely to run into serious mismatches between compiler/kernel/world/configuration. The older approach of "make world" followed by building and installing a new kernel might work well enough for minor updates. But, when upgrading across major releases, people who don't follow this procedure should expect some problems. Also, note that many upgrades (4.x to 5.0, for instance) may require specific additional steps (renaming or deleting specific files prior to installworld, for instance). Read the UPDATING file carefully, especially at the end, where the currently recommended upgrade sequence is spelled out. 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. Note that upgrading from 3.x or earlier is a bit trickier; read UPDATING carefully. >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message