From owner-freebsd-doc@FreeBSD.ORG Sun Nov 20 19:40:10 2011 Return-Path: Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 08BC31065673 for ; Sun, 20 Nov 2011 19:40:09 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id CE09E8FC16 for ; Sun, 20 Nov 2011 19:40:09 +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 pAKJe9nc055887 for ; Sun, 20 Nov 2011 19:40:09 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.4/8.14.4/Submit) id pAKJe9N5055886; Sun, 20 Nov 2011 19:40:09 GMT (envelope-from gnats) Resent-Date: Sun, 20 Nov 2011 19:40:09 GMT Resent-Message-Id: <201111201940.pAKJe9N5055886@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Chris Rees Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 599C91065670 for ; 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 ; 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 ; 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 To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: Subject: docs/162699: Handbook/Upgrading instructions: should mention delete-old in order X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Chris Rees List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 20 Nov 2011 19:40:10 -0000 >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 @@ + make delete-old + + 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 utmp.h causes + problems in some ports when the new + utmpx.h is installed. + + + mergemaster Now you can update the remaining configuration files, since @@ -1979,6 +1989,14 @@ A full machine reboot is needed now to load the new kernel and new world with new configuration files. + + + make delete-old-libs + + 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. + Note that if you're upgrading from one release of the same &os; @@ -2034,8 +2052,10 @@ &prompt.root; mergemaster -p &prompt.root; cd /usr/src &prompt.root; make installworld +&prompt.root; make delete-old &prompt.root; mergemaster -&prompt.root; reboot +&prompt.root; reboot +&prompt.root; make delete-old-libs Read Further Explanations @@ -2471,6 +2491,70 @@ + + + + + Anton + Shterenlikht + Based on notes provided by + + + + + Deleting obsolete files and directories + + + Deleting obsolete files and directories + + + 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 + /usr/src/ObsoleteFiles.inc. The following + instructions will help you removing these obsolete files during the + system upgrade process. + + After the make + installworld and the subsequent + mergemaster commands have finished successfully, you + should check for obsolete files and libraries as follows: + + &prompt.root; cd /usr/src +&prompt.root; make check-old + + If any obsolete files are found, they can be deleted using the + following commands: + + &prompt.root; make delete-old + + + See /usr/src/Makefile + for more targets of interest. + + + 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 BATCH_DELETE_OLD_FILES make-variable as + follows: + + &prompt.root; make -DBATCH_DELETE_OLD_FILES delete-old + + You can also achieve the same goal by piping these commands through + yes like this: + + &prompt.root; yes|make delete-old + + Update Files Not Updated by <command>make installworld</command> @@ -2725,13 +2809,56 @@ Rebooting - You are now done. After you have verified that everything appears - to be in the right place you can reboot the system. A simple + 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: &prompt.root; shutdown -r now + + Deleting obsolete libraries + + + Warning + + 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 make + delete-old-libs is executed. + + + Utilities for checking shared library dependencies are available + from the Ports Collection in sysutils/libchk or sysutils/bsdadminscripts. + + Obsolete shared libraries can conflict with newer libraries, + causing messages like these: + + /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 + + To solve these problems, determine which port installed the + library: + + &prompt.root; pkg_info -W /usr/local/lib/libtiff.so + /usr/local/lib/libtiff.so was installed by package tiff-3.9.4 + &prompt.root; pkg_info -W /usr/local/lib/libXext.so + /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1 + + Then deinstall, rebuild and reinstall the port. The ports-mgmt/portmaster and ports-mgmt/portupgrade 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: + + &prompt.root; make delete-old-libs + + Finished @@ -3020,106 +3147,6 @@ - - - - - Anton - Shterenlikht - Based on notes provided by - - - - Deleting obsolete files, directories and libraries - - Deleting obsolete files, directories and libraries - - - 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 - /usr/src/ObsoleteFiles.inc. The following - instructions will help you removing these obsolete files during the - system upgrade process. - - We assume you are following the steps outlined in . After the make - installworld and the subsequent - mergemaster commands have finished successfully, you - should check for obsolete files and libraries as follows: - - &prompt.root; cd /usr/src -&prompt.root; make check-old - - If any obsolete files are found, they can be deleted using the - following commands: - - &prompt.root; make delete-old - - - See /usr/src/Makefile - for more targets of interest. - - - 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 BATCH_DELETE_OLD_FILES make-variable as - follows: - - &prompt.root; make -DBATCH_DELETE_OLD_FILES delete-old - - You can also achieve the same goal by piping these commands through - yes like this: - - &prompt.root; yes|make delete-old - - - Warning - 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 make - delete-old-libs is executed. - - - Utilities for checking shared library dependencies are available from - the Ports Collection in sysutils/libchk or sysutils/bsdadminscripts. - - Obsolete shared libraries can conflict with newer libraries, - causing messages like these: - - /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 - - To solve these problems, determine which port installed the - library: - - &prompt.root; pkg_info -W /usr/local/lib/libtiff.so -/usr/local/lib/libtiff.so was installed by package tiff-3.9.4 -&prompt.root; pkg_info -W /usr/local/lib/libXext.so -/usr/local/lib/libXext.so was installed by package libXext-1.1.1,1 - - Then deinstall, rebuild and reinstall the port. The ports-mgmt/portmaster and ports-mgmt/portupgrade 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: - - &prompt.root; make delete-old-libs - - --- makeworld.diff ends here --- >Release-Note: >Audit-Trail: >Unformatted: