Date: Sun, 20 Nov 2011 19:35:53 GMT From: Chris Rees <utisoft@gmail.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/162699: Handbook/Upgrading instructions: should mention delete-old in order Message-ID: <201111201935.pAKJZroO055600@freefall.freebsd.org> Resent-Message-ID: <201111201940.pAKJe9N5055886@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>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@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:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201111201935.pAKJZroO055600>