From 52ee421a00b6a536cd05a7c3e847f4e532965693 Mon Sep 17 00:00:00 2001 From: Giorgos Keramidas Date: Sun, 1 Feb 2009 04:25:22 +0000 Subject: [PATCH] Add an explanation of the reasons that buildworld, buildkernel, installkernel, reboot, ... is a good idea. Before describing every step in detail, we let the reader know "why" so that they can later appreciate the "how" a bit more, and feel less confused about the whole dance. PR: docs/43941 Submitted by: kientzle Reviewed by: trhodes --- .../books/handbook/cutting-edge/chapter.sgml | 187 +++++++++++++++++- 1 file changed, 184 insertions(+), 3 deletions(-) diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml index a50cae24ce..bf09ab0468 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml @@ -1588,9 +1588,190 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile The Canonical Way to Update Your System To update your system, you should check - /usr/src/UPDATING for any pre-buildworld steps - necessary for your version of the sources and then use the following - procedure: + /usr/src/UPDATING for any pre-buildworld + steps necessary for your version of the sources and then use the + procedure outlined here. + + These upgrade steps assume that you are currently using an old + &os; version, consisting of an old compiler, old kernel, old world and + old configuration files. By world here we mean the + core system binaries, libraries and programming files. The compiler + is part of world, but has a few special concerns. + + We also assume that you have already obtained the sources to a + newer system. If the sources available on the particular system are + old too, see for detailed help about + synchronizing them to a newer version. + + Updating the system from sources is a bit more subtle 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 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. + + + + 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 we describe in + the following paragraphs. This is not an exhaustive list of all the + reasons why you should prefer the currently recommended upgrade + process. Some of the less obvious ones are listed below: + + + + 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: + + + + 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. + + + + make buildkernel + + Unlike the older approach, using &man.config.8; and + &man.make.1;, this uses the new compiler + residing in /usr/obj. + This protects you 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's already running. It also minimizes any problems from + running the old world on a new kernel. + + + + mergemaster + + 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 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. You now + have a new kernel and new world on disk. + + + + mergemaster + + Now you can update the remaining configuration files, since + you have a new world on disk. + + + + 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 one release of the same &os; + branch to a more recent release of the same branch, i.e. from 7.0 to + 7.1, then this procedure may not be absolutely necessary, since + you're unlikely to run into serious mismatches between compiler, + kernel, userland and configuration files. 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. + + It is also worth noting that many upgrades + (i.e. 4.X to 5.0) may require + specific additional steps (renaming or deleting specific files prior + to installworld, for instance). Read + the /usr/src/UPDATING file carefully, + especially at the end, where the currently recommended upgrade + sequence is explicitly 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. + + + Upgrading from &os; 3.X or earlier + releases is a bit trickier; read UPDATING + carefully if you have to perform this sort of upgrade. + + + To summarize, the currently recommended way of upgrading &os; + from sources is: &prompt.root; cd /usr/src &prompt.root; make buildworld