Attachment 61021 Details for Bug 91518 – file.diff

[patch] file.diff

file.diff (text/plain), 14.31 KB, created by Siebrand Mazeland on 2006-01-08 17:10:05 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Siebrand Mazeland

Created: 2006-01-08 17:10:05 UTC

Size: 14.31 KB

patch

obsolete

>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 @@
> 
> 
> <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.&nbsp;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;&nbsp;4.X) and
>+	and
> 	<filename>/etc/make.conf</filename>.  The first contains some
> 	default defines &ndash; 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;&nbsp;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;&nbsp;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&nbsp;MHz
>-          &pentium;&nbsp;III with 128&nbsp;MB of RAM takes about 2&nbsp;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&nbsp;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&nbsp;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;&nbsp;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

Actions: View | Diff

Attachments on bug 91518: 61021