docs/162699: Handbook/Upgrading instructions: should mention delete-old in order
Chris Rees
utisoft at gmail.com
Sun Nov 20 19:40:10 UTC 2011
>Number: 162699
>Category: docs
>Synopsis: Handbook/Upgrading instructions: should mention delete-old in order
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: doc-bug
>Submitter-Id: current-users
>Arrival-Date: Sun Nov 20 19:40:09 UTC 2011
>Closed-Date:
>Last-Modified:
>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 at 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:
>Unformatted:
More information about the freebsd-doc
mailing list