svn commit: r44735 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Dru Lavigne
dru at FreeBSD.org
Thu May 1 19:38:05 UTC 2014
Author: dru
Date: Thu May 1 19:38:04 2014
New Revision: 44735
URL: http://svnweb.freebsd.org/changeset/doc/44735
Log:
Finish editorial review of Rebuilding World chapter.
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 May 1 18:50:44 2014 (r44734)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu May 1 19:38:04 2014 (r44735)
@@ -1559,7 +1559,8 @@ Script started, output file is /var/tmp/
rebuilt before old libraries are removed using the
instructions in <xref linkend="ports-upgrading"/>. When
finished, remove any obsolete libraries to avoid conflicts
- with newer ones.</para>
+ with newer ones. For a more detailed description of this
+ step, refer to <xref linkend="make-delete-old"/>.</para>
<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
</step>
@@ -1733,40 +1734,48 @@ Script started, output file is /var/tmp/
</primary>
</indexterm>
- <para>&man.mergemaster.8; is a Bourne script to aid in
+ <para>&os; provides the &man.mergemaster.8; Bourne script to aid in
determining the differences between the configuration files
in <filename>/etc</filename>, and the configuration files in
- the source tree <filename>/usr/src/etc</filename>. This is
+ <filename>/usr/src/etc</filename>. This is
the recommended solution for keeping the system
configuration files up to date with those located in the
source tree.</para>
+
+ <para>Before using <command>mergemaster</command>, it is recommended to first copy the existing
+ <filename>/etc</filename> somewhere
+ safe. Include <option>-R</option> which does a recursive copy and
+ <option>-p</option> which preserves times and the ownerships on
+ files:</para>
+
+ <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
- <para>To begin, type <command>mergemaster</command> and it
- will build a temporary root environment, from
- <filename>/</filename> down, and populate it with various
+ <para>When run, <command>mergemaster</command>
+ builds a temporary root environment, from
+ <filename>/</filename> down, and populates it with various
system configuration files. Those files are then compared
to the ones currently installed in the system. Files that
differ will be shown in &man.diff.1; format, with the
<option>+</option> sign representing added or modified
lines, and <option>-</option> representing lines that will
- be either removed completely, or replaced with a new file.
- Refer to &man.diff.1; for more information about the
- &man.diff.1; syntax and how file differences are
+ be either removed completely or replaced with a new file.
+ Refer to &man.diff.1; for more information about
+ how file differences are
shown.</para>
- <para>&man.mergemaster.8; will then display each file that
- differs, and present the options of either deleting the new
- file, referred to as the temporary file, installing the
- temporary file in its unmodified state, merging the
- temporary file with the currently installed file, or viewing
- the &man.diff.1; results again.</para>
+ <para>Next, <command>mergemaster</command> will display each file that
+ differs, and present options to: delete the new
+ file, referred to as the temporary file, install the
+ temporary file in its unmodified state, merge the
+ temporary file with the currently installed file, or view
+ the results again.</para>
<para>Choosing to delete the temporary file will tell
- &man.mergemaster.8; to keep the current file unchanged and
- to delete the new version. This option is not recommended,
- unless there is no reason to change the current file. To
+ <command>mergemaster</command> to keep the current file unchanged and
+ to delete the new version. This option is not recommended.
+ To
get help at any time, type <keycap>?</keycap> at the
- &man.mergemaster.8; prompt. If the user chooses to skip a
+ <command>mergemaster</command> prompt. If the user chooses to skip a
file, it will be presented again after all other files have
been dealt with.</para>
@@ -1785,90 +1794,16 @@ Script started, output file is /var/tmp/
option is customarily used for files where settings have
been modified by the user.</para>
- <para>Choosing to view the &man.diff.1; results again will
- display the file differences just like &man.mergemaster.8;
- did before prompting an option.</para>
+ <para>Choosing to view the results again will
+ redisplay the file differences.</para>
- <para>After &man.mergemaster.8; is done with the system files,
- it will prompt for other options. &man.mergemaster.8; may
+ <para>After <command>mergemaster</command> is done with the system files,
+ it will prompt for other options. It may
prompt to rebuild the password file and will finish up with
an option to remove left-over temporary files.</para>
-
- <para>To perform the update manually instead, do not just copy
- over the files from
- <filename>/usr/src/etc</filename> to
- <filename>/etc</filename> and expect it to
- work. Some files must be <quote>installed</quote> first as
- <filename>/usr/src/etc</filename>
- <emphasis>is not</emphasis> a copy of what
- <filename>/etc</filename> should look
- like. In addition, some files that should be in
- <filename>/etc</filename> are not in
- <filename>/usr/src/etc</filename>.</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>
-
- <warning>
- <title>Backup Your Existing
- <filename>/etc</filename></title>
-
- <para>It is recommended to first copy the existing
- <filename>/etc</filename> somewhere
- safe, like so:</para>
-
- <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen>
-
- <para>where <option>-R</option> does a recursive copy and
- <option>-p</option> preserves times and the ownerships on
- files.</para>
- </warning>
-
- <para>Build a temporary set of directories into which the new
- <filename>/etc</filename> and other files
- can be installed:</para>
-
- <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput>
-&prompt.root; <userinput>cd /usr/src/etc</userinput>
-&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen>
-
- <para>This will build the necessary directory structure and
- install the files. A lot of the subdirectories that have
- been created under <filename>/var/tmp/root</filename> are
- empty and should be deleted. The simplest way to do this is
- to:</para>
-
- <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput>
-&prompt.root; <userinput>find -d . -type d | xargs rmdir 2>/dev/null</userinput></screen>
-
- <para>This will remove all empty directories while redirecting
- standard error to <filename>/dev/null</filename> to prevent
- the warnings about the directories that are not
- empty.</para>
-
- <para><filename>/var/tmp/root</filename> now
- contains all the files that should be placed in appropriate
- locations below <filename>/</filename>.
- Go through each of these files, determining how they differ
- from the system's existing files.</para>
-
- <para>Some of the files installed into
- <filename>/var/tmp/root</filename> have a leading
- <quote>.</quote>. Make sure to use
- <command>ls -a</command> in order to catch them.</para>
-
- <para>The simplest way to compare files is to use
- &man.diff.1;:</para>
-
- <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen>
-
- <para>This command will show the differences between the
- existing <filename>/etc/shells</filename> and the new
- <filename>/var/tmp/root/etc/shells</filename>. Review the
- differences to decide whether to merge in custom changes
- or to replace the existing file with the new one.</para>
-
+<!--
+Probably not needed as changes should be minimal and mergemaster does
+a good job of merging.
<tip>
<title>Name the New Root Directory
(<filename>/var/tmp/root</filename>)
@@ -1946,11 +1881,12 @@ Script started, output file is /var/tmp/
<screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen>
</tip>
+ -->
</sect2>
<sect2 xml:id="make-delete-old">
<info>
- <title>Deleting Obsolete Files and Directories</title>
+ <title>Deleting Obsolete Files and Libraries</title>
<authorgroup>
<author>
@@ -1971,9 +1907,9 @@ Script started, output file is /var/tmp/
their contents occasionally become obsolete. This may be
because functionality is implemented elsewhere, the version
number of the library has changed, or it was removed from the
- system entirely. This includes old files, libraries, and
- directories, which should be removed when updating the system.
- The benefit is that the system is not cluttered with old files
+ system entirely. These obsoleted files, libraries, and
+ directories should be removed when updating the system.
+ This ensures that the system is not cluttered with old files
which take up unnecessary space on the storage and backup
media. Additionally, if the old library has a security or
stability issue, the system should be updated to the newer
@@ -1987,8 +1923,7 @@ Script started, output file is /var/tmp/
<para>After the
<command>make installworld</command>
and the subsequent <command>mergemaster</command> have
- finished successfully, check for obsolete files and libraries
- as follows:</para>
+ finished successfully, check for obsolete files and libraries:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make check-old</userinput></screen>
@@ -1998,11 +1933,6 @@ Script started, output file is /var/tmp/
<screen>&prompt.root; <userinput>make delete-old</userinput></screen>
- <tip>
- <para>Refer to <filename>/usr/src/Makefile</filename>
- for more targets of interest.</para>
- </tip>
-
<para>A prompt is displayed before deleting each obsolete file.
To skip the prompt and let the system remove these files
automatically, use
@@ -2014,10 +1944,6 @@ Script started, output file is /var/tmp/
through <command>yes</command>:</para>
<screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
- </sect2>
-
- <sect2 xml:id="make-delete-old-libs">
- <title>Deleting obsolete libraries</title>
<warning>
<title>Warning</title>
@@ -2031,9 +1957,8 @@ Script started, output file is /var/tmp/
executed.</para>
</warning>
- <para>Utilities for checking shared library dependencies are
- available from the Ports Collection in
- <package>sysutils/libchk</package> or
+ <para>Utilities for checking shared library dependencies include
+ <package>sysutils/libchk</package> and
<package>sysutils/bsdadminscripts</package>.</para>
<para>Obsolete shared libraries can conflict with newer
@@ -2050,22 +1975,19 @@ Script started, output file is /var/tmp/
&prompt.root; <userinput>pkg which /usr/local/lib/libXext.so</userinput>
/usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen>
- <para>Then deinstall, rebuild, and reinstall the port.
+ <para>Then deinstall, rebuild, and reinstall the port. To automate this process,
<package>ports-mgmt/portmaster</package> can
- be used to automate this process. After all ports are rebuilt
+ be used. After all ports are rebuilt
and no longer use the old libraries, delete the old libraries
using the following command:</para>
<screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
- <para>You should now have successfully upgraded the &os;
- system. Congratulations.</para>
-
- <para>If things went slightly wrong, it is easy to rebuild a
+ <para>If something goes wrong, it is easy to rebuild a
particular piece of the system. For example, if
<filename>/etc/magic</filename> was accidentally deleted as
part of the upgrade or merge of <filename>/etc</filename>,
- &man.file.1; will stop working. To fix this, run:</para>
+ <command>file</command> will stop working. To fix this, run:</para>
<screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput>
&prompt.root; <userinput>make all install</userinput></screen>
More information about the svn-doc-all
mailing list