Date: Sun, 8 Jan 2006 18:06:19 +0100 (CET) From: Siebrand Mazeland <s.mazeland@xs4all.nl> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/91518: [patch] Update handbook section "Rebuilding 'world'" in cutting-edge chapter Message-ID: <20060108170619.D168661C2C@nfishbone.nitro.dk> Resent-Message-ID: <200601081710.k08HA6XC084996@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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 <procedure>, 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 @@ <!-- The FreeBSD Documentation Project - $FreeBSD: doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v 1.221 2006/01/02 23:29:53 simon Exp $ + $FreeBSD$ --> <chapter id="cutting-edge"> @@ -551,16 +551,16 @@ tree to rebuild the system.</para> <warning> - <title>Take a Backup</title> + <title>Make a Backup</title> - <para>It cannot be stressed enough how important it is to take a + <para>It cannot be stressed enough how important it is to make a backup of your system <emphasis>before</emphasis> 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.</para> - <para>Make sure you have taken a backup. And have a fixit floppy or + <para>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!</para> @@ -603,18 +603,26 @@ the procedure described here should be used instead.</para> </warning> - <sect2> - <title>The Canonical Way to Update Your System</title> + <sect2 id="updatesystem"> + <title>The Canonical Way to Update a System</title> - <para>To update your system, you should check - <filename>/usr/src/UPDATING</filename> for any pre-buildworld steps - necessary for your version of the sources and then use the following - procedure:</para> + <para>To update a system use the following procedure. Each step + is detailed further down this section:</para> - <screen>&prompt.root; <userinput>make buildworld</userinput> -&prompt.root; <userinput>make buildkernel</userinput> -&prompt.root; <userinput>make installkernel</userinput> -&prompt.root; <userinput>reboot</userinput></screen> + <procedure> + <step> + <para><link linkend="read-updating">Read</link> + <filename>/usr/src/UPDATING</filename> and look for any + pre-buildworld steps necessary for your version of the + sources.</para> + </step> + + <step> + <para><link linkend="compile-base">Compile the source for the + base system</link> using <command>make + buildworld</command>:</para> + + <screen>&prompt.root; <userinput>make buildworld</userinput></screen> <note> <para>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.</para> </note> + </step> + + <step> + <para>Compile a <link linkend="compile-install-kernel">new + kernel</link>:</para> + + <screen>&prompt.root; <userinput>make buildkernel</userinput></screen> + </step> + + <step> + <para>Install the <link linkend="compile-install-kernel">new + kernel</link>:</para> + + <screen>&prompt.root; <userinput>make installkernel</userinput></screen> + </step> + <step> <para>After <maketarget>installkernel</maketarget> finishes - successfully, you should boot in single user mode + successfully, boot in <link + linkend="makeworld-singleuser">single user mode</link> (i.e. using <command>boot -s</command> from the loader - prompt). Then run:</para> + prompt).</para> - <screen>&prompt.root; <userinput>mergemaster -p</userinput> -&prompt.root; <userinput>make installworld</userinput> -&prompt.root; <userinput>mergemaster</userinput> -&prompt.root; <userinput>reboot</userinput></screen> + <screen>&prompt.root; <userinput>reboot</userinput></screen> + + </step> + + <step> + <para>Run &man.mergemaster.8; in pre-buildworld mode, so that + only files known to be essential to the success of + installworld, including <filename>/etc/make.conf</filename> + are compared:</para> + + <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen> + </step> + + <step> + <para><link linkend="make-installworld">Install</link> the + new system binaries:</para> + + <screen>&prompt.root; <userinput>make installworld</userinput></screen> + </step> + + <step> + <para>Remaking the world will not update certain directories + (in particular, <filename>/etc</filename>, + <filename>/var</filename> and <filename>/usr</filename>) + with new or changed configuration files. Use <link + linkend="mergemaster">mergemaster</link> to update these + files:</para> + + <screen>&prompt.root; <userinput>mergemaster</userinput></screen> + </step> + + <step> + <para>Reboot after verifying that everything appears to be in + the right place:</para> + + <screen>&prompt.root; <userinput>reboot</userinput></screen> + </step> + </procedure> <warning> <title>Read Further Explanations</title> @@ -645,7 +704,7 @@ </warning> </sect2> - <sect2> + <sect2 id="read-updating"> <title>Read <filename>/usr/src/UPDATING</filename></title> <para>Before you do anything else, read @@ -672,7 +731,7 @@ <para>Examine the files <filename>/usr/share/examples/etc/make.conf</filename> - (called <filename>/etc/defaults/make.conf</filename> in &os; 4.X) and + and <filename>/etc/make.conf</filename>. 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 @@ <makevar>NO_PROFILE</makevar> (or <makevar>NOPROFILE</makevar> on &os; 5.X and older) lines found in <filename>/usr/share/examples/etc/make.conf</filename> - (or in <filename>/etc/defaults/make.conf</filename> on &os; 4.X) to + to <filename>/etc/make.conf</filename> and uncomment them.</para> <para>Examine the other definitions (<makevar>COPTFLAGS</makevar>, @@ -727,17 +786,11 @@ the same GID but a different name to those in <filename>/usr/src/etc/group</filename>.</para> - <para>Since 4.6-RELEASE you can run &man.mergemaster.8; in + <para>The command &man.mergemaster.8; can run in pre-buildworld mode by providing the <option>-p</option> option. This will compare only those files that are essential for the success of <maketarget>buildworld</maketarget> or - <maketarget>installworld</maketarget>. If your old version of - <command>mergemaster</command> does not support <option>-p</option>, - use the new version in the source tree when running for the first - time:</para> - - <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/mergemaster</userinput> -&prompt.root; <userinput>./mergemaster.sh -p</userinput></screen> + <maketarget>installworld</maketarget>.</para> <tip> <para>If you are feeling particularly paranoid, you can check your @@ -829,8 +882,8 @@ &prompt.root; <userinput>rm -rf *</userinput></screen> </sect2> - <sect2> - <title>Recompile the Source</title> + <sect2 id="compile-base"> + <title>Compile the Source for the Base System</title> <sect3> <title>Saving the Output</title> @@ -921,9 +974,7 @@ <screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen> - <para>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 + <para>The <maketarget>world</maketarget> target has been split in two: <maketarget>buildworld</maketarget> and <maketarget>installworld</maketarget>. Beginning with version @@ -936,7 +987,7 @@ and <maketarget>installworld</maketarget> installs this tree on the current machine.</para> - <para>This is very useful for 2 reasons. First, it allows you + <para>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 <quote>self hosted</quote>. Because of this, you can safely @@ -979,11 +1030,6 @@ <para>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.</para> - - <para>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.</para> </sect3> <sect3> @@ -993,14 +1039,14 @@ <secondary>timings</secondary> </indexterm> - <para>Many factors influence the build time, but currently a 500 MHz - &pentium; III with 128 MB of RAM takes about 2 hours to build + <para>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.</para> </sect3> </sect2> - <sect2> + <sect2 id="compile-install-kernel"> <title>Compile and Install a New Kernel</title> <indexterm> <primary>kernel</primary> @@ -1023,7 +1069,7 @@ can then build a new kernel based on your normal kernel configuration file.</para> - <para>On modern versions of FreeBSD it is important to <link + <para>On FreeBSD it is important to <link linkend="make-buildworld">build world</link> before building a new kernel.</para> @@ -1056,7 +1102,7 @@ <xref linkend="makeworld-singleuser">.</para> </sect2> - <sect2> + <sect2 id="make-installworld"> <title>Install the New System Binaries</title> <para>If you were building a version of &os; recent enough to have @@ -1186,7 +1232,7 @@ not in <filename>/usr/src/etc</filename>.</para> <para>If you are using &man.mergemaster.8; (as recommended), - you can skip forward to the <link linkend="update-dev">next + you can skip forward to the <link linkend="cutting-edge-rebooting">next section</link>.</para> <para>The simplest way to do this by hand is to install the @@ -1333,103 +1379,8 @@ </tip> </sect3> </sect2> - - <sect2 id="update-dev"> - <title>Update <filename>/dev</filename></title> - - <note> - <indexterm><primary>DEVFS</primary></indexterm> - <para>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.</para> - </note> - - <para>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.</para> - - <para>For safety's sake, this is a multi-step process.</para> - - <procedure> - <step> - <para>Copy <filename>/var/tmp/root/dev/MAKEDEV</filename> to - <filename>/dev</filename>:</para> - - <screen>&prompt.root; <userinput>cp /var/tmp/root/dev/MAKEDEV /dev</userinput></screen> - <indexterm> - <primary><filename>MAKEDEV</filename></primary> - </indexterm> - - <para>If you used &man.mergemaster.8; to - update <filename>/etc</filename>, then your - <filename>MAKEDEV</filename> script should have been updated - already, though it cannot hurt to check (with &man.diff.1;) - and copy it manually if necessary.</para> - </step> - - <step> - <para>Now, take a snapshot of your current - <filename>/dev</filename>. 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:</para> - - <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>ls -l | awk '{print $1, $2, $3, $4, $5, $6, $NF}' > /var/tmp/dev.out</userinput></screen> - </step> - - <step> - <para>Remake all the device nodes:</para> - - <screen>&prompt.root; <userinput>sh MAKEDEV all</userinput></screen> - </step> - - <step> - <para>Write another snapshot of the directory, this time to - <filename>/var/tmp/dev2.out</filename>. 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.</para> - - <screen>&prompt.root; <userinput>diff /var/tmp/dev.out /var/tmp/dev2.out</userinput></screen> - - <para>You are most likely to notice disk slice discrepancies which - will involve commands such as:</para> - - <screen>&prompt.root; <userinput>sh MAKEDEV sd0s1</userinput></screen> - - <para>to recreate the slice entries. Your precise circumstances may - vary.</para> - </step> - </procedure> - </sect2> - <sect2> - <title>Update <filename>/stand</filename></title> - - <note> - <para>This step is included only for completeness. It can safely be - omitted. If you are using FreeBSD 5.2 or later, the - <filename>/rescue</filename> directory is automatically updated - for the user with current, statically compiled binaries during - <command>make installworld</command>, thus obsoleting the need - to update <filename>/stand</filename> (which does not exist at - all on &os; 6.0 and later).</para> - </note> - - <para>For the sake of completeness, you may want to update the files in - <filename>/stand</filename> as well. These files consist of hard - links to the <filename>/stand/sysinstall</filename> binary. This - binary should be statically linked, so that it can work when no other - file systems (and in particular <filename>/usr</filename>) have been - mounted.</para> - - <screen>&prompt.root; <userinput>cd /usr/src/release/sysinstall</userinput> -&prompt.root; <userinput>make all install</userinput></screen> - </sect2> - - <sect2> + <sect2 id="cutting-edge-rebooting"> <title>Rebooting</title> <para>You are now done. After you have verified that everything appears >Release-Note: >Audit-Trail: >Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20060108170619.D168661C2C>