--- upgrading.mm	2003/03/10 07:53:36	4.1
+++ upgrading.mm	2003/06/24 05:27:22
@@ -1,9 +1,9 @@
 .\" This file is in -*- nroff-fill -*- mode
-.\" STATUS: final draft 4th edition
+.\" STATUS: 4th edition
 .\"
 .\" To do: add info about disabled devices
 .\"
-.\" $Id: upgrading.mm,v 4.1 2003/03/10 07:53:36 grog Exp $
+.\" $Id: upgrading.mm,v 4.9 2003/05/04 03:23:03 grog Exp grog $
 .Chapter \*[nchupgrading] "Updating the system software"
 .Pn make-world
 .X "make world"
@@ -23,9 +23,9 @@
 at the same release level.  We'll look at the interaction between kernel and
 userland below.
 .LI
-The kernel.  You may build a new kernel without updating the software, of
-course, if you want to add functionality to the kernel.  In this chapter we'll
-look at upgrading the kernel in the context of a complete system upgrade.  We'll
+The kernel.  You may build a new kernel without updating the sources, of course,
+if you want to add functionality to the kernel.  In this chapter we'll look at
+upgrading the kernel in the context of a complete system upgrade.  We'll
 consider building a custom kernel in the next chapter,
 .Sref "\*[chbuild]" .
 .LI
@@ -78,14 +78,12 @@
 \fBname#\fBUsage#\fBPopulated by
 _
 .TH N
-.X "/bin"
 .X "directory, /bin"
 /bin#T{
 Executable programs of general use.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/boot"
 .X "directory, /boot"
 /boot#T{
 Files used when booting the system.
@@ -93,8 +91,8 @@
 \fImake install\fP\/ in
 .Directory /usr/src/sys .
 T}
-.X "/dev"
 .X "directory, /dev"
+.X "/dev, directory"
 /dev#T{
 Directory of device nodes.
 T}#T{
@@ -102,103 +100,78 @@
 System startup (\fIdevfs\fP\/)
 .hy
 T}
-.X "/sbin"
-.X "directory, /sbin"
-.X "/etc"
 .X "directory, /etc"
 /etc#T{
 Configuration files used at system startup.
 T}#T{
 Install from CD-ROM only, \fImergemaster\fP, administrator
 T}
-.X "/sbin"
 .X "directory, /sbin"
 \fI/sbin#T{
 System executables needed at system startup time.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/stand"
-.X "directory, /stand"
-/stand#T{
-Directory with \fIstandalone\fP\/ programs.
-T}#T{
-\fImake install\fP\/ in
-.Directory /usr/src/stand
-T}
-.X "/usr/X11R6"
 .X "directory, /usr/X11R6"
 /usr/X11R6#T{
 The X11 windowing system.
 T}#T{
 X-based programs in the Ports Collection
 T}
-.X "/usr/bin"
 .X "directory, /usr/bin"
 /usr/bin#T{
 Standard executable programs that are not needed at system start.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/compat"
 .X "directory, /usr/compat"
 /usr/compat#T{
 A directory containing code for emulated systems, such as Linux.
 T}#T{
 Ports Collection
 T}
-.X "/usr/games"
 .X "directory, /usr/games"
 /usr/games#T{
 Games.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/include"
 .X "directory, /usr/include"
 /usr/include#T{
 Header files for programmers.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/lib"
 .X "directory, /usr/lib"
-.X "/lib"
-.X "directory, /lib"
 /usr/lib#T{
 Library files.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/libexec"
 .X "directory, /usr/libexec"
 /usr/libexec#T{
 Executable files that are not started directly by the user.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/libdata"
 .X "directory, /usr/libdata"
 /usr/libdata#T{
 Miscellaneous files used by system utilities.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/local"
 .X "directory, /usr/local"
 /usr/local#T{
 Additional programs that are not part of the operating system.
 T}#T{
 Ports collection
 T}
-.X "/usr/obj"
 .X "directory, /usr/obj"
 /usr/obj#T{
 Temporary object files created when building the system.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/ports"
 .X "directory, /usr/ports"
 /usr/ports#T{
 The Ports Collection.
@@ -206,21 +179,18 @@
 .Command sysinstall ,
 \fIcvs\fP\/
 T}
-.X "/usr/sbin"
 .X "directory, /usr/sbin"
 /usr/sbin#T{
 System administration programs that are not needed at system startup.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/share"
 .X "directory, /usr/share"
 /usr/share#T{
 Miscellaneous read-only files, mainly informative.
 T}#T{
 \fImake world\fP\/
 T}
-.X "/usr/src"
 .X "directory, /usr/src"
 /usr/src#T{
 System source files.
@@ -232,6 +202,7 @@
 .TE
 .ad b
 .H2 "Upgrading kernel and userland"
+.Pn buildworld
 The core part of a system upgrade consists of a synchronized update of both
 kernel and userland.  It's relatively simple to do, but depending on the speed
 of the machine, it may keep the computer busy for several hours.  In general,
@@ -278,6 +249,7 @@
 (\fIreboot\fP\/)
 # \f(CBmake installworld\fP
 .De
+.ne 3v
 You'll find information about such requirements in the file
 .File /usr/src/UPDATING .
 Table \*[build-targets] gives an overview of the more useful targets to the
@@ -314,7 +286,12 @@
 .Dx
 # \f(CBmake buildkernel KERNCONF=MYKERNEL\fP
 .De
+By default, this target builds all the KLDs (Kernel Loadable Modules), which
+significantly increases the time it takes.  If you know that your KLDs will not
+change, or that you won't be using any, you can skip building them by specifying
+the \f(CW-DNO_MODULES\fP flag.
 T}
+.sp .4v
 installkernel#T{
 Install a kernel you have built with \f(CWbuildkernel\fP.
 T}
@@ -336,11 +313,12 @@
 process added a daemon user and group, both called \f(CWsmmsp\fP.  To install
 the userland, this user already needed to be present.
 .P
+.ne 10v
 The solution to this issue is called \fImergemaster\fP, a script that helps you
 to upgrade the configuration files.  We'll look at it in more detail below, but
 at this point you should know that you need to run it with the \f(CW-p\fP
 (\fIpre-build\fP\/) option:
-.Dx
+.Dx 1
 # \f(CBmergemaster -p\fP
 .De
 As we've seen in table
@@ -371,11 +349,11 @@
 # \f(CBfind . -mtime +10 | xargs rm\fP
 .De
 This command removes all files in the current directory
-.File -n ( . )
+.Directory -n ( . )
 that are older than 10 days (\f(CW+10\fP).  Of course, this method will only
 work if you haven't installed anything in these directories yourself.  You
 shouldn't have done so; that's the purpose of the directory hierarchy
-.Directory /usr/local/ ,
+.Directory /usr/local ,
 to ensure that you keep system files apart from ports and private files.
 .P
 Be careful with
@@ -397,6 +375,7 @@
 in Chapter
 .Sref \*[nchbuild] .
 .P
+.ne 3v
 One point to notice is that if you're upgrading from an older custom
 configuration file, you could have a lot of trouble.  We'll see a strategy for
 minimizing the pain on page
@@ -405,9 +384,9 @@
 FreeBSD, you need to install a file
 .File /boot/device.hints ,
 which you can typically copy from
-.File /usr/src/sys/i386/GENERIC.hints \/:
+.File /usr/src/sys/i386/conf/GENERIC.hints \/:
 .Dx
-# \f(CBcp /usr/src/sys/i386/GENERIC.hints /boot/device.hints\fP
+# \f(CBcp /usr/src/sys/i386/conf/GENERIC.hints /boot/device.hints\fP
 .De
 See page
 .Sref "\*[IO-config]" \&
@@ -441,12 +420,32 @@
 .H2 "Upgrading the boot files"
 At the time of writing, it's still necessary to install the files in
 .Directory /boot
-separately.  Do this with:
-.Dx
-# \f(CBcd /usr/src/sys\fP
-# \f(CBmake install\fP
-.De
-It's possible that this requirement will go away in the future.
+separately.  It's possible that this requirement will go away in the future.
+There are two steps: first you build and install the boot files in then
+.Directory /boot
+directory, then you install them on your boot disk.  Assuming your system disk
+is the SCSI disk
+.Device da0 ,
+you would perform some of the following steps.
+.Dx
+# \f(CBcd /usr/src/sys\fP                       \fIbuild directory\fP\/
+# \f(CBmake install\fP                          \fIbuild and install the bootstraps\fP\/
+# \f(CBbsdlabel -B da0\fP                       \fIfor a dedicated disk\fP\/
+# \f(CBbsdlabel -B da0s1\fP                     \fIfor a PC disk slice\fP\/
+# \f(CBboot0cfg -B da0\fP                       \fIinstall booteasy on a PC\fP\/
+.De
+If you have a dedicated disk, which is normal on a non-Intel platform, use the
+first
+.Command bsdlabel
+invocation to install the bootstrap
+.Command -n ( boot1 )
+at the beginning of the disk.  Otherwise, install
+.Command -n boot1
+at the beginning of your FreeBSD slice and use
+.Command boot0cfg
+to install the  
+.Command -n boot0
+boot manager at the beginning of the disk.
 .H2 "Upgrading the configuration files"
 Currently, the system build procedure does not install the configuration files
 in 
@@ -663,10 +662,11 @@
 some ports use it, so it's preferable to recreate it.  Do this with the
 \&\f(CW-p\fP  option to
 .Command pwd_mkdb \/:
-.Dx
+.Dx 1
 # \f(CBpwd_mkdb -p /etc/master.passwd\fP
 .De
 .SPUP
+.ne 10v
 .H2 "Merging /etc/group"
 In addition to
 .File /etc/master.passwd ,
@@ -724,7 +724,7 @@
 entry and leave your entry in the file, preserving the users.
 .LI
 In addition, you may have some users in other groups.  For example, installing
-.Command postfix \&
+.Daemon postfix \&
 adds the user \f(CWpostfix\fP to group \f(CWmail\fP.  You need to preserve these
 users.
 .Le
@@ -773,7 +773,7 @@
 Run
 .Command mergemaster
 in the same way as before, saving the output.  If you haven't deleted the old
-.File /var/tmp/temproot
+.Directory /var/tmp/temproot
 directory, you might see:
 .Dx
 # \f(CBmergemaster -ia 2>&1 | tee -a /var/tmp/merge\fP
@@ -903,7 +903,7 @@
 still in
 .File /etc/crontab .
 The lines starting with \f(CW+\fP show lines only in the new file, which is in
-.File /var/tmp/temproot.1102.15.01.14/etc/crontab .
+.File -n /var/tmp/temproot.1102.15.01.14/etc/crontab .
 There are a number of changes here: the CVS ID (\f(CW$FreeBSD$\fP) has changed
 from 1.21 to 1.31, and the times of the periodic maintenance have changed.  In
 the meantime, though, you have added other tasks (the bottom four lines), and
@@ -945,11 +945,11 @@
 You definitely need to merge this one yourself.
 .LI
 If you're using
-.Command postfix ,
+.Daemon postfix ,
 don't install the distribution version of
 .File /etc/mail/mailer.conf .
 It will reenable
-.Command sendmail ,
+.Daemon sendmail ,
 which can cause significant problems.
 .LI
 If you have changed anything in
