From owner-svn-doc-all@FreeBSD.ORG Thu May 1 19:38:05 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 4587E25D; Thu, 1 May 2014 19:38:05 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 31EA7147B; Thu, 1 May 2014 19:38:05 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s41Jc4hT012092; Thu, 1 May 2014 19:38:04 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s41Jc4Bx012091; Thu, 1 May 2014 19:38:04 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201405011938.s41Jc4Bx012091@svn.freebsd.org> From: Dru Lavigne Date: Thu, 1 May 2014 19:38:04 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44735 - head/en_US.ISO8859-1/books/handbook/cutting-edge X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 01 May 2014 19:38:05 -0000 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 . When finished, remove any obsolete libraries to avoid conflicts - with newer ones. + with newer ones. For a more detailed description of this + step, refer to . &prompt.root; make delete-old-libs @@ -1733,40 +1734,48 @@ Script started, output file is /var/tmp/ - &man.mergemaster.8; is a Bourne script to aid in + &os; provides the &man.mergemaster.8; Bourne script to aid in determining the differences between the configuration files in /etc, and the configuration files in - the source tree /usr/src/etc. This is + /usr/src/etc. This is the recommended solution for keeping the system configuration files up to date with those located in the source tree. + + Before using mergemaster, it is recommended to first copy the existing + /etc somewhere + safe. Include which does a recursive copy and + which preserves times and the ownerships on + files: + + &prompt.root; cp -Rp /etc /etc.old - To begin, type mergemaster and it - will build a temporary root environment, from - / down, and populate it with various + When run, mergemaster + builds a temporary root environment, from + / 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 sign representing added or modified lines, and 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. - &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. + Next, mergemaster 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. 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 + mergemaster to keep the current file unchanged and + to delete the new version. This option is not recommended. + To get help at any time, type ? at the - &man.mergemaster.8; prompt. If the user chooses to skip a + mergemaster prompt. If the user chooses to skip a file, it will be presented again after all other files have been dealt with. @@ -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. - Choosing to view the &man.diff.1; results again will - display the file differences just like &man.mergemaster.8; - did before prompting an option. + Choosing to view the results again will + redisplay the file differences. - After &man.mergemaster.8; is done with the system files, - it will prompt for other options. &man.mergemaster.8; may + After mergemaster 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. - - To perform the update manually instead, do not just copy - over the files from - /usr/src/etc to - /etc and expect it to - work. Some files must be installed first as - /usr/src/etc - is not a copy of what - /etc should look - like. In addition, some files that should be in - /etc are not in - /usr/src/etc. - - 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. - - - Backup Your Existing - <filename>/etc</filename> - - It is recommended to first copy the existing - /etc somewhere - safe, like so: - - &prompt.root; cp -Rp /etc /etc.old - - where does a recursive copy and - preserves times and the ownerships on - files. - - - Build a temporary set of directories into which the new - /etc and other files - can be installed: - - &prompt.root; mkdir /var/tmp/root -&prompt.root; cd /usr/src/etc -&prompt.root; make DESTDIR=/var/tmp/root distrib-dirs distribution - - This will build the necessary directory structure and - install the files. A lot of the subdirectories that have - been created under /var/tmp/root are - empty and should be deleted. The simplest way to do this is - to: - - &prompt.root; cd /var/tmp/root -&prompt.root; find -d . -type d | xargs rmdir 2>/dev/null - - This will remove all empty directories while redirecting - standard error to /dev/null to prevent - the warnings about the directories that are not - empty. - - /var/tmp/root now - contains all the files that should be placed in appropriate - locations below /. - Go through each of these files, determining how they differ - from the system's existing files. - - Some of the files installed into - /var/tmp/root have a leading - .. Make sure to use - ls -a in order to catch them. - - The simplest way to compare files is to use - &man.diff.1;: - - &prompt.root; diff /etc/shells /var/tmp/root/etc/shells - - This command will show the differences between the - existing /etc/shells and the new - /var/tmp/root/etc/shells. Review the - differences to decide whether to merge in custom changes - or to replace the existing file with the new one. - + - Deleting Obsolete Files and Directories + Deleting Obsolete Files and Libraries @@ -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/ After the make installworld and the subsequent mergemaster have - finished successfully, check for obsolete files and libraries - as follows: + finished successfully, check for obsolete files and libraries: &prompt.root; cd /usr/src &prompt.root; make check-old @@ -1998,11 +1933,6 @@ Script started, output file is /var/tmp/ &prompt.root; make delete-old - - Refer to /usr/src/Makefile - for more targets of interest. - - 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 yes: &prompt.root; yes|make delete-old - - - - Deleting obsolete libraries Warning @@ -2031,9 +1957,8 @@ Script started, output file is /var/tmp/ executed. - Utilities for checking shared library dependencies are - available from the Ports Collection in - sysutils/libchk or + Utilities for checking shared library dependencies include + sysutils/libchk and sysutils/bsdadminscripts. Obsolete shared libraries can conflict with newer @@ -2050,22 +1975,19 @@ Script started, output file is /var/tmp/ &prompt.root; pkg which /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. + Then deinstall, rebuild, and reinstall the port. To automate this process, ports-mgmt/portmaster 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: &prompt.root; make delete-old-libs - You should now have successfully upgraded the &os; - system. Congratulations. - - If things went slightly wrong, it is easy to rebuild a + If something goes wrong, it is easy to rebuild a particular piece of the system. For example, if /etc/magic was accidentally deleted as part of the upgrade or merge of /etc, - &man.file.1; will stop working. To fix this, run: + file will stop working. To fix this, run: &prompt.root; cd /usr/src/usr.bin/file &prompt.root; make all install