svn commit: r43806 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Dru Lavigne
dru at FreeBSD.org
Thu Feb 6 17:20:15 UTC 2014
Author: dru
Date: Thu Feb 6 17:20:15 2014
New Revision: 43806
URL: http://svnweb.freebsd.org/changeset/doc/43806
Log:
More incorporation of redundant information. Definitely very much a WIP.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu Feb 6 16:49:50 2014 (r43805)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu Feb 6 17:20:15 2014 (r43806)
@@ -1544,6 +1544,18 @@ before running "/usr/sbin/freebsd-update
the function of each command.</para>
<step>
+ <para>If the build world process has previously been run on
+ this system, a copy of the previous build may still exist
+ in <filename class="directory">/usr/obj</filename>. To speed up the new build world
+ process, and possibly save some dependency headaches,
+ remove this directory if it already exists:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/obj</userinput>
+&prompt.root; <userinput>chflags -R noschg *</userinput>
+&prompt.root; <userinput>rm -rf *</userinput></screen>
+ </step>
+
+ <step>
<para>Compile the new compiler and a few related
tools, then use the new compiler to compile the rest of
the new world. The result is saved to
@@ -1577,11 +1589,12 @@ before running "/usr/sbin/freebsd-update
<screen>&prompt.root; <userinput>shutdown now</userinput></screen>
- <para>Once in single-user mode, run this command if the
+ <para>Once in single-user mode, run these commands if the
system is formatted with UFS:</para>
<screen>&prompt.root; <userinput>mount -u /</userinput>
-&prompt.root; <userinput>mount -a -t ufs</userinput></screen>
+&prompt.root; <userinput>mount -a -t ufs</userinput>
+&prompt.root; <userinput>swapon -a</userinput></screen>
<para>If the system is instead formatted with ZFS, run these
two commands. This example assumes a zpool name of
@@ -1592,18 +1605,22 @@ before running "/usr/sbin/freebsd-update
</step>
<step>
- <para>Then, for either filesystem, run:</para>
+ <para>Then, for either file system, if the <acronym>CMOS</acronym> clock is set to local time
+ (this is true if the output of &man.date.1; does not show
+ the correct time and zone), run:</para>
<screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
</step>
<step>
- <para>Next, perform some initial configuration file updates
- in preparation for the new world. For instance, this step
- may add new groups or new system accounts which have been
+ <para>Next, perform some initial configuration file updates to <filename class="directory">/etc</filename>
+ in preparation for the new world. The following command compares
+ only those files that are essential for the success of
+ <buildtarget>installworld</buildtarget>. For instance, this step
+ may add new groups, system accounts, or startup scripts which have been
added to &os; since the last update. This is necessary so
that the <buildtarget>installworld</buildtarget> step will
- be able to use the new system accounts and groups.</para>
+ be able to use any new system accounts, groups, and scripts.</para>
<screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
</step>
@@ -1646,42 +1663,51 @@ before running "/usr/sbin/freebsd-update
<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
</step>
</procedure>
+
+ <indexterm><primary>single-user mode</primary></indexterm>
+
+ <para>If the system can have a window of down-time, consider compiling the system in single user mode instead
+ of compiling the system in multi-user
+ mode, and then dropping into single user mode for the
+ installation.
+ Reinstalling the system touches a lot of important system
+ files, all the standard system binaries, libraries, and
+ include files. Changing these on a running system,
+ particularly one with active users, is asking for
+ trouble.</para>
</sect2>
<sect2 xml:id="src-updating">
- <title>Check <filename>/etc/make.conf</filename></title>
+ <title>Configuration Files</title>
<indexterm>
<primary><filename>make.conf</filename></primary>
</indexterm>
- <para>The following sections clearly describe each step,
- especially when using a custom kernel configuration.</para>
- <para>Available &man.make.1; options are shown in
- &man.make.conf.5; and
- <filename>/usr/share/examples/etc/make.conf</filename>. These
- settings can be added to <filename>/etc/make.conf</filename>
- to control the way &man.make.1; runs and how it builds
- programs. Changes to some settings can have far-reaching and
- potentially surprising effects. Read the comments in both
- locations and keep in mind that the defaults have been chosen
- for a combination of performance and safety.</para>
+ <para>This section describes the configuration files used by the
+ build world process.</para>
- <para>Options set in <filename>/etc/make.conf</filename> take
+ <para>The options available to &man.make.1; are described in
+ &man.make.conf.5; and some common examples are included in
+ <filename>/usr/share/examples/etc/make.conf</filename>.
+ Any options which are added to <filename>/etc/make.conf</filename>
+ will control the way &man.make.1; runs and how it builds
+ programs. Such options take
effect every time &man.make.1; is used, including compiling
- applications from the Ports Collection or user-written C
+ applications from the Ports Collection, compiling custom C
programs, or building the &os; operating system.</para>
- </sect2>
-
- <sect2 xml:id="src-conf">
- <title>Check <filename>/etc/src.conf</filename></title>
+
+ <para>Changes to some settings can have far-reaching and
+ potentially surprising effects. Read the comments in both
+ locations and keep in mind that the defaults have been chosen
+ for a combination of performance and safety.</para>
<indexterm>
<primary><filename>src.conf</filename></primary>
</indexterm>
- <para><filename>/etc/src.conf</filename> controls the building
- of the operating system from source code. Unlike
+ <para>How
+ the operating system is built from source code is controlled by <filename>/etc/src.conf</filename>. Unlike
<filename>/etc/make.conf</filename>, the contents of
<filename>/etc/src.conf</filename> only take effect when the
&os; operating system itself is being built. Descriptions of
@@ -1689,116 +1715,7 @@ before running "/usr/sbin/freebsd-update
&man.src.conf.5;. Be cautious about disabling seemingly
unneeded kernel modules and build options. Sometimes there
are unexpected or subtle interactions.</para>
- </sect2>
-
- <sect2 xml:id="updating-etc">
- <title>Update the Files in <filename>/etc</filename></title>
-
- <para><filename>/etc</filename> contains a
- large part of the system's configuration information, as well
- as scripts that are run at system startup. Some of these
- scripts change between &os; versions.</para>
-
- <para>Some of the configuration files are used in the day to
- day running of the system, such as
- <filename>/etc/group</filename>.</para>
-
- <para>There have been occasions when the installation part of
- <command>make installworld</command> expected certain
- usernames or groups to exist. When performing an upgrade, it
- is likely that these users or groups do not yet exist. In
- some cases <command>make buildworld</command> will check to
- see if these users or groups exist.</para>
-
- <para>The solution is to run &man.mergemaster.8; in
- pre-buildworld mode with <option>-p</option>. This compares
- only those files that are essential for the success of
- <buildtarget>buildworld</buildtarget> or
- <buildtarget>installworld</buildtarget>.</para>
-
- <tip>
- <para>To check which files are owned by the group being
- renamed or deleted:</para>
-
- <screen>&prompt.root; <userinput>find / -group GID -print</userinput></screen>
-
- <para>This command will show all files owned by group
- <replaceable>GID</replaceable>, which can be either a group
- name or a numeric group ID.</para>
- </tip>
- </sect2>
-
- <sect2 xml:id="makeworld-singleuser">
- <title>Drop to Single User Mode</title>
-
- <indexterm><primary>single-user mode</primary></indexterm>
-
- <para>Consider compiling the system in single user mode.
- Reinstalling the system touches a lot of important system
- files, all the standard system binaries, libraries, and
- include files. Changing these on a running system,
- particularly one with active users, is asking for
- trouble.</para>
-
- <indexterm><primary>multi-user mode</primary></indexterm>
- <para>Another method is to compile the system in multi-user
- mode, and then drop into single user mode for the
- installation. With this method, hold off on the following
- steps until the build has completed. Drop to single user mode
- in order to run <buildtarget>installkernel</buildtarget> or
- <buildtarget>installworld</buildtarget>.</para>
-
- <para>To enter single user mode from a running system:</para>
-
- <screen>&prompt.root; <userinput>shutdown now</userinput></screen>
-
- <para>Alternatively, reboot the system, and at the boot prompt,
- select the <quote>single user</quote> option. Once at the
- single user mode shell prompt, run:</para>
-
- <screen>&prompt.root; <userinput>fsck -p</userinput>
-&prompt.root; <userinput>mount -u /</userinput>
-&prompt.root; <userinput>mount -a -t ufs</userinput>
-&prompt.root; <userinput>swapon -a</userinput></screen>
-
- <para>This checks the file systems, remounts
- <filename>/</filename> read/write, mounts all the other UFS
- file systems referenced in <filename>/etc/fstab</filename>,
- and turns swapping on.</para>
-
- <note>
- <para>If the CMOS clock is set to local time and not to GMT
- (this is true if the output of &man.date.1; does not show
- the correct time and zone), run the following
- command:</para>
-
- <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen>
-
- <para>This ensures that the local time-zone settings get set
- up correctly.</para>
- </note>
- </sect2>
-
- <sect2 xml:id="cleaning-usr-obj">
- <title>Remove <filename>/usr/obj</filename></title>
-
- <para>As parts of the system are rebuilt, they are, by default,
- placed in subdirectories of <filename>/usr/obj</filename>.
- The directories shadow those under
- <filename>/usr/src</filename>.</para>
-
- <para>To speed up the <command>make buildworld</command>
- process, and possibly save some dependency headaches,
- remove this directory if it already exists.</para>
-
- <para>Some files below <filename>/usr/obj</filename> may have
- the immutable flag set which must be removed first using
- &man.chflags.1;.</para>
-
- <screen>&prompt.root; <userinput>cd /usr/obj</userinput>
-&prompt.root; <userinput>chflags -R noschg *</userinput>
-&prompt.root; <userinput>rm -rf *</userinput></screen>
- </sect2>
+ </sect2>
<sect2 xml:id="make-buildworld">
<title>Recompile the Base System</title>
@@ -2005,16 +1922,9 @@ Script done, …</screen>
problems. See &man.init.8; for details about
<varname>kern.securelevel</varname> and &man.chflags.1; for
details about the various file flags.</para>
- </sect2>
-
- <sect2 xml:id="new-kernel-singleuser">
- <title>Reboot into Single User Mode</title>
-
- <indexterm><primary>single-user mode</primary></indexterm>
<para>Reboot into single user mode to test that the new kernel
- works using the instructions in
- <xref linkend="makeworld-singleuser"/>.</para>
+ works.</para>
</sect2>
<sect2 xml:id="make-installworld">
@@ -2160,11 +2070,6 @@ Script done, …</screen>
<filename>/etc</filename> are 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="updating-upgrading-rebooting">next
- section</link>.</para>
-
<para>The simplest way to merge files by hand is to install
the files into a new directory, and then work through them
looking for differences.</para>
@@ -2376,15 +2281,6 @@ Script done, …</screen>
<screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
</sect2>
- <sect2 xml:id="updating-upgrading-rebooting">
- <title>Rebooting</title>
-
- <para>Verify that everything appears to be in the right place,
- then reboot the system using &man.shutdown.8;:</para>
-
- <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
- </sect2>
-
<sect2 xml:id="make-delete-old-libs">
<title>Deleting obsolete libraries</title>
@@ -2607,10 +2503,10 @@ Building everything..
</varlistentry>
<varlistentry>
- <term>What do I do if something goes wrong?</term>
+ <term>What if something goes wrong?</term>
<listitem>
- <para>Make absolutely sure that the environment has no
+ <para>First, make absolutely sure that the environment has no
extraneous cruft from earlier builds:</para>
<screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
More information about the svn-doc-all
mailing list