From crees@FreeBSD.org  Sun Nov 20 19:35:54 2011
Return-Path: <crees@FreeBSD.org>
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 599C91065670
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 20 Nov 2011 19:35:54 +0000 (UTC)
	(envelope-from crees@FreeBSD.org)
Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28])
	by mx1.freebsd.org (Postfix) with ESMTP id EE9678FC0C
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 20 Nov 2011 19:35:53 +0000 (UTC)
Received: from freefall.freebsd.org (localhost [127.0.0.1])
	by freefall.freebsd.org (8.14.4/8.14.4) with ESMTP id pAKJZrIs055601
	for <FreeBSD-gnats-submit@freebsd.org>; Sun, 20 Nov 2011 19:35:53 GMT
	(envelope-from crees@freefall.freebsd.org)
Received: (from crees@localhost)
	by freefall.freebsd.org (8.14.4/8.14.4/Submit) id pAKJZroO055600;
	Sun, 20 Nov 2011 19:35:53 GMT
	(envelope-from crees)
Message-Id: <201111201935.pAKJZroO055600@freefall.freebsd.org>
Date: Sun, 20 Nov 2011 19:35:53 GMT
From: Chris Rees <utisoft@gmail.com>
Reply-To: Chris Rees <crees@freebsd.org>
To: FreeBSD-gnats-submit@freebsd.org
Cc:
Subject: Handbook/Upgrading instructions: should mention delete-old in order
X-Send-Pr-Version: 3.113
X-GNATS-Notify:

>Number:         162699
>Category:       docs
>Synopsis:       Handbook/Upgrading instructions: should mention delete-old in order
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    crees
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Sun Nov 20 19:40:09 UTC 2011
>Closed-Date:    Wed May 29 17:50:30 UTC 2013
>Last-Modified:  Wed May 29 18:00:00 UTC 2013
>Originator:     Chris Rees
>Release:        FreeBSD 8.2-STABLE i386
>Organization:
>Environment:
System: FreeBSD freefall.freebsd.org 8.2-STABLE FreeBSD 8.2-STABLE #4 r220774: Mon Apr 18 13:56:14 UTC 2011 simon@freefall.freebsd.org:/usr/obj/usr/src/sys/FREEFALL i386


	
>Description:
	[1] describes a case where the system has been upgraded wrongly,
presumably because the Handbook doesn't make it clear how important the
make delete-old stages are, although they are documented in src/Makefile.

	The attached moves the section on make delete-old and delete-old-libs
into the main upgrading section, and adds the steps to the instructions.

	Rendered at: http://www.bayofrum.net/~crees/rendered/makeworld.html

[1] http://www.freebsd.org/cgi/cvsweb.cgi/ports/shells/zsh/files/patch-Src_watch.c
>How-To-Repeat:
	
>Fix:

	I understand it's usually better practice to make two diffs; one moving
the section and the other with the content changes; I'm happy to provide those
if the change is OK.

--- makeworld.diff begins here ---
Index: cutting-edge/chapter.sgml
===================================================================
RCS file: /home/dcvs/doc/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml,v
retrieving revision 1.255
diff -u -r1.255 chapter.sgml
--- cutting-edge/chapter.sgml	23 Aug 2011 18:40:43 -0000	1.255
+++ cutting-edge/chapter.sgml	20 Nov 2011 19:29:07 -0000
@@ -1967,6 +1967,16 @@
 	</listitem>
 
 	<listitem>
+	  <para><command>make <maketarget>delete-old</maketarget></command></para>
+
+	  <para>This target deletes old (obsolete) files.  This is important
+	    because sometimes they cause problems if left on the disk, for
+	    example the presence of the old <filename>utmp.h</filename> causes
+	    problems in some ports when the new
+	    <filename>utmpx.h</filename> is installed.</para>
+	</listitem>
+
+	<listitem>
 	  <para><command>mergemaster</command></para>
 
 	  <para>Now you can update the remaining configuration files, since
@@ -1979,6 +1989,14 @@
 	  <para>A full machine reboot is needed now to load the new kernel
 	    and new world with new configuration files.</para>
 	</listitem>
+
+	<listitem>
+	  <para><command>make <maketarget>delete-old-libs</maketarget></command></para>
+
+	  <para>Remove any obsolete libraries to avoid conflicts with newer
+	    ones.  Make sure that all ports have been rebuilt to use the new
+	    libraries before you delete the old ones.</para>
+	</listitem>
       </orderedlist>
 
       <para>Note that if you're upgrading from one release of the same &os;
@@ -2034,8 +2052,10 @@
 &prompt.root; <userinput>mergemaster -p</userinput>
 &prompt.root; <userinput>cd /usr/src</userinput>
 &prompt.root; <userinput>make installworld</userinput>
+&prompt.root; <userinput>make delete-old</userinput>
 &prompt.root; <userinput>mergemaster</userinput>
-&prompt.root; <userinput>reboot</userinput></screen>
+&prompt.root; <userinput>reboot</userinput>
+&prompt.root; <userinput>make delete-old-libs</userinput></screen>
 
       <warning>
 	<title>Read Further Explanations</title>
@@ -2471,6 +2491,70 @@
       </note>
     </sect2>
 
+    <sect2 id="make-delete-old">
+      <sect2info>
+	<authorgroup>
+	  <author>
+	    <firstname>Anton</firstname>
+	    <surname>Shterenlikht</surname>
+	    <contrib>Based on notes provided by </contrib>
+	  </author>
+	</authorgroup>
+      </sect2info>
+
+      <title>Deleting obsolete files and directories</title>
+
+      <indexterm>
+	<primary>Deleting obsolete files and directories</primary>
+      </indexterm>
+
+      <para>As a part of the &os; development lifecycle, it happens from time
+	to time that files and their contents become obsolete.  This may be
+	because their 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 for the user is that
+	the system is not cluttered with old files which take up unnecessary
+	space on the storage (and backup) medium.  Additionally, if the old
+	library had a security or stability issue, you should update to the
+	newer library to keep your system safe and prevent crashes caused by
+	the old library implementation.  The files, directories, and libraries
+	that are considered obsolete are listed in
+	<filename>/usr/src/ObsoleteFiles.inc</filename>.  The following
+	instructions will help you removing these obsolete files during the
+	system upgrade process.</para>
+
+      <para>After the <command>make
+	<maketarget>installworld</maketarget></command> and the subsequent
+	<command>mergemaster</command> commands have finished successfully, you
+	should check for obsolete files and libraries as follows:</para>
+
+      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
+&prompt.root; <userinput>make check-old</userinput></screen>
+
+      <para>If any obsolete files are found, they can be deleted using the
+	following commands:</para>
+
+      <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
+
+      <tip>
+	<para>See <filename>/usr/src/Makefile</filename>
+	  for more targets of interest.</para>
+      </tip>
+
+      <para>A prompt is displayed before deleting each obsolete file.  You can
+	skip the prompt and let the system remove these files automatically by
+	using the <makevar>BATCH_DELETE_OLD_FILES</makevar> make-variable as
+	follows:</para>
+
+      <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
+
+      <para>You can also achieve the same goal by piping these commands through
+	<command>yes</command> like this:</para>
+
+      <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
+    </sect2>
+
     <sect2 id="post-installworld-updates">
       <title>Update Files Not Updated by <command>make installworld</command></title>
 
@@ -2725,13 +2809,56 @@
     <sect2 id="updating-upgrading-rebooting">
       <title>Rebooting</title>
 
-      <para>You are now done.  After you have verified that everything appears
-	to be in the right place you can reboot the system.  A simple
+      <para>You are now almost done.  After you have verified that everything
+	appears to be in the right place you can reboot the system.  A simple
 	&man.shutdown.8; should do it:</para>
 
       <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
     </sect2>
 
+    <sect2 id="updating-upgrading-make-delete-old-libs">
+      <title>Deleting obsolete libraries</title>
+
+      <warning>
+	<title>Warning</title>
+
+	<para>Deleting obsolete files will break applications that still
+	  depend on those obsolete files.  This is especially true for old
+	  libraries. In most cases, you need to recompile the programs, ports,
+	  or libraries that used the old library before <command>make
+	<maketarget>delete-old-libs</maketarget></command> is executed.</para>
+      </warning>
+
+      <para>Utilities for checking shared library dependencies are available
+	from the Ports Collection in <filename
+	role="package">sysutils/libchk</filename> or <filename
+	role="package">sysutils/bsdadminscripts</filename>.</para>
+
+      <para>Obsolete shared libraries can conflict with newer libraries,
+	causing messages like these:</para>
+
+      <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
+/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
+
+      <para>To solve these problems, determine which port installed the
+	library:</para>
+
+      <screen>&prompt.root; <userinput>pkg_info -W  /usr/local/lib/libtiff.so</userinput>
+  /usr/local/lib/libtiff.so was installed by package tiff-3.9.4
+  &prompt.root; <userinput>pkg_info -W /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. The <filename
+	role="package">ports-mgmt/portmaster</filename> and <filename
+	role="package">ports-mgmt/portupgrade</filename> utilities can be used
+	to automate this process.  After you've made sure that all ports are
+	rebuilt and do not use the old libraries anymore, you can delete them
+	using the
+	following command:</para>
+
+      <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
+    </sect2>
+
     <sect2>
       <title>Finished</title>
 
@@ -3020,106 +3147,6 @@
     </sect2>
   </sect1>
 
-  <sect1 id="make-delete-old">
-    <sect1info>
-      <authorgroup>
-	<author>
-	  <firstname>Anton</firstname>
-	  <surname>Shterenlikht</surname>
-	  <contrib>Based on notes provided by </contrib>
-	</author>
-      </authorgroup>
-    </sect1info>
-    <title>Deleting obsolete files, directories and libraries</title>
-    <indexterm>
-      <primary>Deleting obsolete files, directories and libraries</primary>
-    </indexterm>
-
-    <para>As a part of the &os; development lifecycle, it happens from time
-      to time that files and their contents become obsolete.  This may be
-      because their 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 for the user is that
-      the system is not cluttered with old files which take up unnecessary
-      space on the storage (and backup) medium.  Additionally, if the old
-      library had a security or stability issue, you should update to the
-      newer library to keep your system safe and prevent crashes caused by
-      the old library implementation.  The files, directories, and libraries
-      that are considered obsolete are listed in
-      <filename>/usr/src/ObsoleteFiles.inc</filename>.  The following
-      instructions will help you removing these obsolete files during the
-      system upgrade process.</para>
-
-    <para>We assume you are following the steps outlined in <xref
-      linkend="canonical-build">.  After the <command>make
-      <maketarget>installworld</maketarget></command> and the subsequent
-      <command>mergemaster</command> commands have finished successfully, you
-      should check for obsolete files and libraries as follows:</para>
-
-    <screen>&prompt.root; <userinput>cd /usr/src</userinput>
-&prompt.root; <userinput>make check-old</userinput></screen>
-
-    <para>If any obsolete files are found, they can be deleted using the
-      following commands:</para>
-
-    <screen>&prompt.root; <userinput>make delete-old</userinput></screen>
-
-    <tip>
-      <para>See <filename>/usr/src/Makefile</filename>
-        for more targets of interest.</para>
-    </tip>
-
-    <para>A prompt is displayed before deleting each obsolete file.  You can
-      skip the prompt and let the system remove these files automatically by
-      using the <makevar>BATCH_DELETE_OLD_FILES</makevar> make-variable as
-      follows:</para>
-
-    <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
-
-    <para>You can also achieve the same goal by piping these commands through
-      <command>yes</command> like this:</para>
-
-    <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
-
-    <warning>
-      <title>Warning</title>
-        <para>Deleting obsolete files will break applications that still
-          depend on those obsolete files.  This is especially true for old
-          libraries. In most cases, you need to recompile the programs, ports,
-          or libraries that used the old library before <command>make
-      <maketarget>delete-old-libs</maketarget></command> is executed.</para>
-    </warning>
-
-    <para>Utilities for checking shared library dependencies are available from
-      the Ports Collection in <filename
-      role="package">sysutils/libchk</filename> or <filename
-      role="package">sysutils/bsdadminscripts</filename>.</para>
-
-    <para>Obsolete shared libraries can conflict with newer libraries,
-      causing messages like these:</para>
-
-    <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
-/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
-
-    <para>To solve these problems, determine which port installed the
-      library:</para>
-
-    <screen>&prompt.root; <userinput>pkg_info -W  /usr/local/lib/libtiff.so</userinput>
-/usr/local/lib/libtiff.so was installed by package tiff-3.9.4
-&prompt.root; <userinput>pkg_info -W /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. The <filename
-      role="package">ports-mgmt/portmaster</filename> and <filename
-      role="package">ports-mgmt/portupgrade</filename> utilities can be used to
-      automate this process.  After you've made sure that all ports are rebuilt
-      and do not use the old libraries anymore, you can delete them using the
-      following command:</para>
-
-    <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen>
-  </sect1>
-
   <sect1 id="small-lan">
     <sect1info>
       <authorgroup>
--- makeworld.diff ends here ---


>Release-Note:
>Audit-Trail:

From: Benjamin Kaduk <kaduk@MIT.EDU>
To: Chris Rees <crees@freebsd.org>
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/162699: Handbook/Upgrading instructions: should mention
 delete-old in order
Date: Mon, 21 Nov 2011 01:36:45 -0500 (EST)

 On Sun, 20 Nov 2011, Chris Rees wrote:
 
 > 	I understand it's usually better practice to make two diffs; one moving
 > the section and the other with the content changes; I'm happy to provide those
 > if the change is OK.
 
 A smaller diff with just the content changes is easier to review.
 
 That said, a quick once-over on the full diff seems okay.  Thanks for 
 putting it together.
 
 -Ben Kaduk

From: Chris Rees <crees@freebsd.org>
To: Benjamin Kaduk <kaduk@mit.edu>, bug-followup@freebsd.org
Cc:  
Subject: Re: docs/162699: Handbook/Upgrading instructions: should mention
 delete-old in order
Date: Mon, 21 Nov 2011 09:58:10 +0000

 On 21 November 2011 06:36, Benjamin Kaduk <kaduk@mit.edu> wrote:
 > On Sun, 20 Nov 2011, Chris Rees wrote:
 >
 >> =A0 =A0 =A0 =A0I understand it's usually better practice to make two dif=
 fs; one
 >> moving
 >> the section and the other with the content changes; I'm happy to provide
 >> those
 >> if the change is OK.
 >
 > A smaller diff with just the content changes is easier to review.
 >
 > That said, a quick once-over on the full diff seems okay. =A0Thanks for
 > putting it together.
 
 Yeah, I'll make another diff then when I get back home.  Should be a few ho=
 urs.
 
 Thanks for the review.
 
 Chris

From: Chris Rees <crees@freebsd.org>
To: bug-followup@freebsd.org
Cc:  
Subject: Re: docs/162699: Handbook/Upgrading instructions: should mention
 delete-old in order
Date: Sat, 17 Dec 2011 13:03:41 +0000

 Hey,
 
 Sorry about the huge delay :/
 
 New patches:
 
 For moving the content:
 http://www.bayofrum.net/~crees/patches/doc-cutting-edge-move-make-delete-old.diff
 
 For editing the moved content:
 http://www.bayofrum.net/~crees/patches/doc-cutting-edge-content-changes.diff
 
 Applying patch 1 then patch 2 should give the correct result.
 
 Chris
Responsible-Changed-From-To: freebsd-doc->eadler 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Fri May 4 04:19:04 UTC 2012 
Responsible-Changed-Why:  
I'll take it. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=162699 
Responsible-Changed-From-To: eadler->freebsd-doc 
Responsible-Changed-By: eadler 
Responsible-Changed-When: Wed Jul 25 06:42:10 UTC 2012 
Responsible-Changed-Why:  
I won't be getting to this any time soon 

http://www.freebsd.org/cgi/query-pr.cgi?pr=162699 
Responsible-Changed-From-To: freebsd-doc->crees 
Responsible-Changed-By: crees 
Responsible-Changed-When: Wed May 29 13:50:04 UTC 2013 
Responsible-Changed-Why:  
I can deal. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=162699 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/162699: commit references a PR
Date: Wed, 29 May 2013 17:46:37 +0000 (UTC)

 Author: crees
 Date: Wed May 29 17:46:29 2013
 New Revision: 41772
 URL: http://svnweb.freebsd.org/changeset/doc/41772
 
 Log:
   Removing old files is not an optional step on updating and upgrading FreeBSD.
   Reflect this by merging make delete-old section into the updating section.
   
   This is a movement-only change; the content change will follow
   
   PR:		docs/162699
   Approved by:	gjb (mentor)
 
 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	Wed May 29 15:05:43 2013	(r41771)
 +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml	Wed May 29 17:46:29 2013	(r41772)
 @@ -2630,6 +2630,72 @@ Script done, &hellip;</screen>
        </sect3>
      </sect2>
  
 +    <sect2 id="make-delete-old">
 +      <sect2info>
 +	<authorgroup>
 +	  <author>
 +	    <firstname>Anton</firstname>
 +	    <surname>Shterenlikht</surname>
 +	    <contrib>Based on notes provided by </contrib>
 +	  </author>
 +	</authorgroup>
 +      </sect2info>
 +      <title>Deleting Obsolete Files, Directories and Libraries</title>
 +
 +      <indexterm>
 +	<primary>Deleting obsolete files, directories and
 +	  libraries</primary>
 +      </indexterm>
 +
 +      <para>As a part of the &os; development lifecycle, files and 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 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 library to keep
 +	it safe and to prevent crashes caused by the old library.
 +	Files, directories, and libraries which are considered obsolete
 +	are listed in <filename>/usr/src/ObsoleteFiles.inc</filename>.
 +	The following instructions should be used to remove obsolete
 +	files during the system upgrade process.</para>
 +
 +      <para>Follow the steps outlined in <xref
 +	  linkend="canonical-build"/>.  After the
 +	<command>make <maketarget>installworld</maketarget></command>
 +	and the subsequent <command>mergemaster</command> have finished
 +	successfully, check for obsolete files and libraries as
 +	follows:</para>
 +
 +      <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 +  &prompt.root; <userinput>make check-old</userinput></screen>
 +
 +      <para>If any obsolete files are found, they can be deleted using
 +	the following command:</para>
 +
 +      <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
 +	<makevar>BATCH_DELETE_OLD_FILES</makevar>:</para>
 +
 +      <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
 +
 +      <para>The same goal can be achieved by piping these commands
 +	through <command>yes</command>:</para>
 +
 +      <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
 +    </sect2>
 +
      <sect2 id="updating-upgrading-rebooting">
        <title>Rebooting</title>
  
 @@ -2637,6 +2703,49 @@ Script done, &hellip;</screen>
  	then reboot the system using &man.shutdown.8;:</para>
  
        <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
 +    </sect2>
 +
 +    <sect2>
 +      <title>Deleting obsolete libraries</title>
 +
 +      <warning>
 +	<title>Warning</title>
 +
 +	<para>Deleting obsolete files will break applications that
 +	  still depend on those obsolete files.  This is especially true
 +	  for old libraries.  In most cases, the programs, ports, or
 +	  libraries that used the old library need to be recompiled
 +	  before <command>make
 +	    <maketarget>delete-old-libs</maketarget></command> is
 +	  executed.</para>
 +      </warning>
 +
 +      <para>Utilities for checking shared library dependencies are
 +	available from the Ports Collection in
 +	<filename role="package">sysutils/libchk</filename> or <filename
 +	  role="package">sysutils/bsdadminscripts</filename>.</para>
 +
 +      <para>Obsolete shared libraries can conflict with newer libraries,
 +	causing messages like these:</para>
 +
 +      <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
 +  /usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
 +
 +      <para>To solve these problems, determine which port installed the
 +	library:</para>
 +
 +      <screen>&prompt.root; <userinput>pkg_info -W  /usr/local/lib/libtiff.so</userinput>
 +  /usr/local/lib/libtiff.so was installed by package tiff-3.9.4
 +  &prompt.root; <userinput>pkg_info -W /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.  <filename
 +	  role="package">ports-mgmt/portmaster</filename> can be used to
 +	automate this process.  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>
 @@ -2921,111 +3030,6 @@ Building everything..
      </sect2>
    </sect1>
  
 -  <sect1 id="make-delete-old">
 -    <sect1info>
 -      <authorgroup>
 -	<author>
 -	  <firstname>Anton</firstname>
 -	  <surname>Shterenlikht</surname>
 -	  <contrib>Based on notes provided by </contrib>
 -	</author>
 -      </authorgroup>
 -    </sect1info>
 -    <title>Deleting Obsolete Files, Directories and Libraries</title>
 -
 -    <indexterm>
 -      <primary>Deleting obsolete files, directories and
 -	libraries</primary>
 -    </indexterm>
 -
 -    <para>As a part of the &os; development lifecycle, files and 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 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 library to keep
 -      it safe and to prevent crashes caused by the old library.
 -      Files, directories, and libraries which are considered obsolete
 -      are listed in <filename>/usr/src/ObsoleteFiles.inc</filename>.
 -      The following instructions should be used to remove obsolete
 -      files during the system upgrade process.</para>
 -
 -    <para>Follow the steps outlined in <xref
 -	linkend="canonical-build"/>.  After the
 -      <command>make <maketarget>installworld</maketarget></command>
 -      and the subsequent <command>mergemaster</command> have finished
 -      successfully, check for obsolete files and libraries as
 -      follows:</para>
 -
 -    <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 -&prompt.root; <userinput>make check-old</userinput></screen>
 -
 -    <para>If any obsolete files are found, they can be deleted using
 -      the following command:</para>
 -
 -    <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
 -      <makevar>BATCH_DELETE_OLD_FILES</makevar>:</para>
 -
 -    <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen>
 -
 -    <para>The same goal can be achieved by piping these commands
 -      through <command>yes</command>:</para>
 -
 -    <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen>
 -
 -    <warning>
 -      <title>Warning</title>
 -
 -      <para>Deleting obsolete files will break applications that
 -	still depend on those obsolete files.  This is especially true
 -	for old libraries.  In most cases, the programs, ports, or
 -	libraries that used the old library need to be recompiled
 -	before <command>make
 -	  <maketarget>delete-old-libs</maketarget></command> is
 -	executed.</para>
 -    </warning>
 -
 -    <para>Utilities for checking shared library dependencies are
 -      available from the Ports Collection in
 -      <filename role="package">sysutils/libchk</filename> or <filename
 -	role="package">sysutils/bsdadminscripts</filename>.</para>
 -
 -    <para>Obsolete shared libraries can conflict with newer libraries,
 -      causing messages like these:</para>
 -
 -    <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
 -/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
 -
 -    <para>To solve these problems, determine which port installed the
 -      library:</para>
 -
 -    <screen>&prompt.root; <userinput>pkg_info -W  /usr/local/lib/libtiff.so</userinput>
 -/usr/local/lib/libtiff.so was installed by package tiff-3.9.4
 -&prompt.root; <userinput>pkg_info -W /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.  <filename
 -	role="package">ports-mgmt/portmaster</filename> can be used to
 -      automate this process.  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>
 -  </sect1>
 -
    <sect1 id="small-lan">
      <sect1info>
        <authorgroup>
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
State-Changed-From-To: open->closed 
State-Changed-By: crees 
State-Changed-When: Wed May 29 17:50:30 UTC 2013 
State-Changed-Why:  
Committed. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=162699 

From: dfilter@FreeBSD.ORG (dfilter service)
To: bug-followup@FreeBSD.org
Cc:  
Subject: Re: docs/162699: commit references a PR
Date: Wed, 29 May 2013 17:50:15 +0000 (UTC)

 Author: crees
 Date: Wed May 29 17:50:03 2013
 New Revision: 41773
 URL: http://svnweb.freebsd.org/changeset/doc/41773
 
 Log:
   Removing old files is not an optional step on updating and upgrading FreeBSD.
   Reflect this by merging make delete-old section into the updating section.
   
   This change rewords the section such that it fits in with the content around it,
   and is the followup commit to r41772.
   
   PR:		docs/162699
   Approved by:	gjb (mentor)
 
 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	Wed May 29 17:46:29 2013	(r41772)
 +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml	Wed May 29 17:50:03 2013	(r41773)
 @@ -1875,11 +1875,30 @@ Fetching 133 new ports or files... done.
  	</listitem>
  
  	<listitem>
 +	  <para><command>make
 +	      <maketarget>delete-old</maketarget></command></para>
 +
 +	  <para>This target deletes old (obsolete) files.  This is important
 +	    because sometimes they cause problems if left on the disk, for
 +	    example the presence of the old <filename>utmp.h</filename>
 +	    causes problems in some ports when the new
 +	    <filename>utmpx.h</filename> is installed.</para>
 +	</listitem>
 +
 +	<listitem>
  	  <para>Reboot.</para>
  
  	  <para>A full machine reboot is needed now to load the new
  	    kernel and new world with new configuration files.</para>
  	</listitem>
 +
 +	<listitem>
 +	  <para><command>make <maketarget>delete-old-libs</maketarget></command></para>
 +
 +	  <para>Remove any obsolete libraries to avoid conflicts with newer
 +	    ones.  Make sure that all ports have been rebuilt
 +	    before old libraries are removed.</para>
 +	</listitem>
        </orderedlist>
  
        <para>Upgrades from one release of the same &os; branch to a
 @@ -1935,7 +1954,9 @@ Fetching 133 new ports or files... done.
  &prompt.root; <userinput>cd /usr/src</userinput>
  &prompt.root; <userinput>make installworld</userinput>
  &prompt.root; <userinput>mergemaster</userinput>
 -&prompt.root; <userinput>reboot</userinput></screen>
 +&prompt.root; <userinput>make delete-old</userinput>
 +&prompt.root; <userinput>reboot</userinput>
 +&prompt.root; <userinput>make delete-old-libs</userinput></screen>
  
        <warning>
  	<title>Read Further Explanations</title>
 @@ -2640,11 +2661,10 @@ Script done, &hellip;</screen>
  	  </author>
  	</authorgroup>
        </sect2info>
 -      <title>Deleting Obsolete Files, Directories and Libraries</title>
 +      <title>Deleting Obsolete Files and Directories</title>
  
        <indexterm>
 -	<primary>Deleting obsolete files, directories and
 -	  libraries</primary>
 +	<primary>Deleting obsolete files and directories</primary>
        </indexterm>
  
        <para>As a part of the &os; development lifecycle, files and their
 @@ -2663,15 +2683,14 @@ Script done, &hellip;</screen>
  	The following instructions should be used to remove obsolete
  	files during the system upgrade process.</para>
  
 -      <para>Follow the steps outlined in <xref
 -	  linkend="canonical-build"/>.  After the
 -	<command>make <maketarget>installworld</maketarget></command>
 +      <para>After the <command>make
 +	<maketarget>installworld</maketarget></command>
  	and the subsequent <command>mergemaster</command> have finished
  	successfully, check for obsolete files and libraries as
  	follows:</para>
  
        <screen>&prompt.root; <userinput>cd /usr/src</userinput>
 -  &prompt.root; <userinput>make check-old</userinput></screen>
 +&prompt.root; <userinput>make check-old</userinput></screen>
  
        <para>If any obsolete files are found, they can be deleted using
  	the following command:</para>
 @@ -2705,7 +2724,7 @@ Script done, &hellip;</screen>
        <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
      </sect2>
  
 -    <sect2>
 +    <sect2 id="make-delete-old-libs">
        <title>Deleting obsolete libraries</title>
  
        <warning>
 @@ -2729,7 +2748,7 @@ Script done, &hellip;</screen>
  	causing messages like these:</para>
  
        <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5
 -  /usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
 +/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen>
  
        <para>To solve these problems, determine which port installed the
  	library:</para>
 _______________________________________________
 svn-doc-all@freebsd.org mailing list
 http://lists.freebsd.org/mailman/listinfo/svn-doc-all
 To unsubscribe, send any mail to "svn-doc-all-unsubscribe@freebsd.org"
 
>Unformatted:
