From owner-freebsd-doc@FreeBSD.ORG Sun Jan 8 17:10:07 2006 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org 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 5096B16A41F for ; Sun, 8 Jan 2006 17:10:07 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 4AB8643D48 for ; Sun, 8 Jan 2006 17:10:06 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.4/8.13.4) with ESMTP id k08HA6fG084997 for ; Sun, 8 Jan 2006 17:10:06 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.4/8.13.4/Submit) id k08HA6XC084996; Sun, 8 Jan 2006 17:10:06 GMT (envelope-from gnats) Resent-Date: Sun, 8 Jan 2006 17:10:06 GMT Resent-Message-Id: <200601081710.k08HA6XC084996@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Siebrand Mazeland Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 344E316A41F for ; Sun, 8 Jan 2006 17:06:33 +0000 (GMT) (envelope-from siebrand@nitro.dk) Received: from nfishbone.nitro.dk (fishbone.nitro.dk [83.95.46.74]) by mx1.FreeBSD.org (Postfix) with ESMTP id 3D46F43D69 for ; Sun, 8 Jan 2006 17:06:21 +0000 (GMT) (envelope-from siebrand@nitro.dk) Received: by nfishbone.nitro.dk (Postfix, from userid 1026) id D168661C2C; Sun, 8 Jan 2006 18:06:19 +0100 (CET) Message-Id: <20060108170619.D168661C2C@nfishbone.nitro.dk> Date: Sun, 8 Jan 2006 18:06:19 +0100 (CET) From: Siebrand Mazeland To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: Subject: docs/91518: [patch] Update handbook section "Rebuilding 'world'" in cutting-edge chapter X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Siebrand Mazeland List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 08 Jan 2006 17:10:07 -0000 >Number: 91518 >Category: docs >Synopsis: [patch] Update handbook section "Rebuilding 'world'" in cutting-edge chapter >Confidential: no >Severity: non-critical >Priority: medium >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: update >Submitter-Id: current-users >Arrival-Date: Sun Jan 08 17:10:05 GMT 2006 >Closed-Date: >Last-Modified: >Originator: Siebrand Mazeland >Release: FreeBSD 5.4-RELEASE-p8 i386 >Organization: >Environment: System: FreeBSD nfishbone.nitro.dk 5.4-RELEASE-p8 FreeBSD 5.4-RELEASE-p8 #8: Sun Oct 23 12:51:06 CEST 2005 simon@nfishbone.nitro.dk:/usr/obj/usr/src/sys/FISHBONE i386 >Description: Update the handbook section "Rebuilding 'world'" in the chapter cutting-edge because it contains some confusing notes and old references. Changes based on experience of updating from 6.0 RELEASE to 6.0 STABLE using the current handbook. More precise: - updating procedure revised (made , added links and tags where needed - updated timings to something more generic and shorter runtime - removed 4.X and earlier specific remarks - removed section on updating /dev (automatic from 5.0 on) - removed section on updating /stand (automatic from 5.2 on) - removed almost 5-year-old remark about -j# being experimental - tiny wording changes (take backup -> make backup, 2 -> two) - removed use of 'modern' in 'make buildworld' before 'make buildkernel' See: - attached patch. - preview build at: http://nitro.dk/~siebrand/PR/makeworld.html >How-To-Repeat: Check http://www.freebsd.org/doc/en/books/handbook/makeworld.html and follow the procedure. >Fix: Index: chapter.sgml =================================================================== RCS file: /home/ncvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v retrieving revision 1.221 diff -u -d -r1.221 chapter.sgml --- chapter.sgml 2 Jan 2006 23:29:53 -0000 1.221 +++ chapter.sgml 8 Jan 2006 16:52:49 -0000 @@ -1,7 +1,7 @@ @@ -551,16 +551,16 @@ tree to rebuild the system. - Take a Backup + Make a Backup - It cannot be stressed enough how important it is to take a + It cannot be stressed enough how important it is to make a backup of your system before you do this. While rebuilding the world is (as long as you follow these instructions) an easy task to do, there will inevitably be times when you make mistakes, or when mistakes made by others in the source tree render your system unbootable. - Make sure you have taken a backup. And have a fixit floppy or + Make sure you have made a backup. And have a fixit floppy or bootable CD at hand. You will probably never have to use it, but it is better to be safe than sorry! @@ -603,18 +603,26 @@ the procedure described here should be used instead. - - The Canonical Way to Update Your System + + The Canonical Way to Update a 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: + To update a system use the following procedure. Each step + is detailed further down this section: - &prompt.root; make buildworld -&prompt.root; make buildkernel -&prompt.root; make installkernel -&prompt.root; reboot + + + Read + /usr/src/UPDATING and look for any + pre-buildworld steps necessary for your version of the + sources. + + + + Compile the source for the + base system using make + buildworld: + + &prompt.root; make buildworld There are a few rare cases when an extra run of @@ -624,16 +632,67 @@ though, you can safely omit this step if you are not updating across one or more major &os; versions. + + + + Compile a new + kernel: + + &prompt.root; make buildkernel + + + + Install the new + kernel: + + &prompt.root; make installkernel + + After installkernel finishes - successfully, you should boot in single user mode + successfully, boot in single user mode (i.e. using boot -s from the loader - prompt). Then run: + prompt). - &prompt.root; mergemaster -p -&prompt.root; make installworld -&prompt.root; mergemaster -&prompt.root; reboot + &prompt.root; reboot + + + + + Run &man.mergemaster.8; in pre-buildworld mode, so that + only files known to be essential to the success of + installworld, including /etc/make.conf + are compared: + + &prompt.root; mergemaster -p + + + + Install the + new system binaries: + + &prompt.root; make installworld + + + + Remaking the world will not update certain directories + (in particular, /etc, + /var and /usr) + with new or changed configuration files. Use mergemaster to update these + files: + + &prompt.root; mergemaster + + + + Reboot after verifying that everything appears to be in + the right place: + + &prompt.root; reboot + + Read Further Explanations @@ -645,7 +704,7 @@ - + Read <filename>/usr/src/UPDATING</filename> Before you do anything else, read @@ -672,7 +731,7 @@ Examine the files /usr/share/examples/etc/make.conf - (called /etc/defaults/make.conf in &os; 4.X) and + and /etc/make.conf. The first contains some default defines – most of which are commented out. To make use of them when you rebuild your system from source, add @@ -686,7 +745,7 @@ NO_PROFILE (or NOPROFILE on &os; 5.X and older) lines found in /usr/share/examples/etc/make.conf - (or in /etc/defaults/make.conf on &os; 4.X) to + to /etc/make.conf and uncomment them. Examine the other definitions (COPTFLAGS, @@ -727,17 +786,11 @@ the same GID but a different name to those in /usr/src/etc/group. - Since 4.6-RELEASE you can run &man.mergemaster.8; in + The command &man.mergemaster.8; can run in pre-buildworld mode by providing the option. This will compare only those files that are essential for the success of buildworld or - installworld. If your old version of - mergemaster does not support , - use the new version in the source tree when running for the first - time: - - &prompt.root; cd /usr/src/usr.sbin/mergemaster -&prompt.root; ./mergemaster.sh -p + installworld. If you are feeling particularly paranoid, you can check your @@ -829,8 +882,8 @@ &prompt.root; rm -rf * - - Recompile the Source + + Compile the Source for the Base System Saving the Output @@ -921,9 +974,7 @@ &prompt.root; make target - Beginning with version 2.2.5 of &os; (actually, it was - first created on the &os.current; branch, and then retrofitted to - &os.stable; midway between 2.2.2 and 2.2.5) the + The world target has been split in two: buildworld and installworld. Beginning with version @@ -936,7 +987,7 @@ and installworld installs this tree on the current machine. - This is very useful for 2 reasons. First, it allows you + This is very useful for two reasons. First, it allows you to do the build safe in the knowledge that no components of your running system will be affected. The build is self hosted. Because of this, you can safely @@ -979,11 +1030,6 @@ If you have a multi-CPU machine and you are using an SMP configured kernel try values between 6 and 10 and see how they speed things up. - - Be aware that this is still somewhat experimental, and commits - to the source tree may occasionally break this feature. If the - world fails to compile using this parameter try again without it - before you report any problems. @@ -993,14 +1039,14 @@ timings - Many factors influence the build time, but currently a 500 MHz - &pentium; III with 128 MB of RAM takes about 2 hours to build + Many factors influence the build time, but fairly recent + machines usually take less than an hour to build the &os.stable; tree, with no tricks or shortcuts used during the process. A &os.current; tree will take somewhat longer. - + Compile and Install a New Kernel kernel @@ -1023,7 +1069,7 @@ can then build a new kernel based on your normal kernel configuration file. - On modern versions of FreeBSD it is important to On FreeBSD it is important to build world before building a new kernel. @@ -1056,7 +1102,7 @@ . - + Install the New System Binaries If you were building a version of &os; recent enough to have @@ -1186,7 +1232,7 @@ not in /usr/src/etc. If you are using &man.mergemaster.8; (as recommended), - you can skip forward to the next + you can skip forward to the next section. The simplest way to do this by hand is to install the @@ -1333,103 +1379,8 @@ - - - Update <filename>/dev</filename> - - - DEVFS - If you are running FreeBSD 5.0 or later you can safely - skip this section. These versions use &man.devfs.5; to - allocate device nodes transparently for the user. - - - In most cases, the &man.mergemaster.8; tool will realize when - it is necessary to update the device nodes, and offer to complete it - automatically. These instructions tell how to update the device - nodes manually. - - For safety's sake, this is a multi-step process. - - - - Copy /var/tmp/root/dev/MAKEDEV to - /dev: - - &prompt.root; cp /var/tmp/root/dev/MAKEDEV /dev - - MAKEDEV - - - If you used &man.mergemaster.8; to - update /etc, then your - MAKEDEV script should have been updated - already, though it cannot hurt to check (with &man.diff.1;) - and copy it manually if necessary. - - - - Now, take a snapshot of your current - /dev. This snapshot needs to contain the - permissions, ownerships, major and minor numbers of each filename, - but it should not contain the time stamps. The easiest way to do - this is to use &man.awk.1; to strip out some of the - information: - - &prompt.root; cd /dev -&prompt.root; ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.out - - - - Remake all the device nodes: - - &prompt.root; sh MAKEDEV all - - - - Write another snapshot of the directory, this time to - /var/tmp/dev2.out. Now look through these - two files for any device node that you missed creating. There should - not be any, but it is better to be safe than sorry. - - &prompt.root; diff /var/tmp/dev.out /var/tmp/dev2.out - - You are most likely to notice disk slice discrepancies which - will involve commands such as: - - &prompt.root; sh MAKEDEV sd0s1 - - to recreate the slice entries. Your precise circumstances may - vary. - - - - - Update <filename>/stand</filename> - - - This step is included only for completeness. It can safely be - omitted. If you are using FreeBSD 5.2 or later, the - /rescue directory is automatically updated - for the user with current, statically compiled binaries during - make installworld, thus obsoleting the need - to update /stand (which does not exist at - all on &os; 6.0 and later). - - - For the sake of completeness, you may want to update the files in - /stand as well. These files consist of hard - links to the /stand/sysinstall binary. This - binary should be statically linked, so that it can work when no other - file systems (and in particular /usr) have been - mounted. - - &prompt.root; cd /usr/src/release/sysinstall -&prompt.root; make all install - - - + Rebooting You are now done. After you have verified that everything appears >Release-Note: >Audit-Trail: >Unformatted: