Date: Thu, 1 May 2014 19:38:04 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> 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 Message-ID: <201405011938.s41Jc4Bx012091@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <xref linkend="ports-upgrading"/>. When finished, remove any obsolete libraries to avoid conflicts - with newer ones.</para> + with newer ones. For a more detailed description of this + step, refer to <xref linkend="make-delete-old"/>.</para> <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen> </step> @@ -1733,40 +1734,48 @@ Script started, output file is /var/tmp/ </primary> </indexterm> - <para>&man.mergemaster.8; is a Bourne script to aid in + <para>&os; provides the &man.mergemaster.8; Bourne script to aid in determining the differences between the configuration files in <filename>/etc</filename>, and the configuration files in - the source tree <filename>/usr/src/etc</filename>. This is + <filename>/usr/src/etc</filename>. This is the recommended solution for keeping the system configuration files up to date with those located in the source tree.</para> + + <para>Before using <command>mergemaster</command>, it is recommended to first copy the existing + <filename>/etc</filename> somewhere + safe. Include <option>-R</option> which does a recursive copy and + <option>-p</option> which preserves times and the ownerships on + files:</para> + + <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen> - <para>To begin, type <command>mergemaster</command> and it - will build a temporary root environment, from - <filename>/</filename> down, and populate it with various + <para>When run, <command>mergemaster</command> + builds a temporary root environment, from + <filename>/</filename> 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 <option>+</option> sign representing added or modified lines, and <option>-</option> 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.</para> - <para>&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.</para> + <para>Next, <command>mergemaster</command> 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.</para> <para>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 + <command>mergemaster</command> to keep the current file unchanged and + to delete the new version. This option is not recommended. + To get help at any time, type <keycap>?</keycap> at the - &man.mergemaster.8; prompt. If the user chooses to skip a + <command>mergemaster</command> prompt. If the user chooses to skip a file, it will be presented again after all other files have been dealt with.</para> @@ -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.</para> - <para>Choosing to view the &man.diff.1; results again will - display the file differences just like &man.mergemaster.8; - did before prompting an option.</para> + <para>Choosing to view the results again will + redisplay the file differences.</para> - <para>After &man.mergemaster.8; is done with the system files, - it will prompt for other options. &man.mergemaster.8; may + <para>After <command>mergemaster</command> 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.</para> - - <para>To perform the update manually instead, do not just copy - over the files from - <filename>/usr/src/etc</filename> to - <filename>/etc</filename> and expect it to - work. Some files must be <quote>installed</quote> first as - <filename>/usr/src/etc</filename> - <emphasis>is not</emphasis> a copy of what - <filename>/etc</filename> should look - like. In addition, some files that should be in - <filename>/etc</filename> are not in - <filename>/usr/src/etc</filename>.</para> - - <para>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.</para> - - <warning> - <title>Backup Your Existing - <filename>/etc</filename></title> - - <para>It is recommended to first copy the existing - <filename>/etc</filename> somewhere - safe, like so:</para> - - <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen> - - <para>where <option>-R</option> does a recursive copy and - <option>-p</option> preserves times and the ownerships on - files.</para> - </warning> - - <para>Build a temporary set of directories into which the new - <filename>/etc</filename> and other files - can be installed:</para> - - <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput> -&prompt.root; <userinput>cd /usr/src/etc</userinput> -&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen> - - <para>This will build the necessary directory structure and - install the files. A lot of the subdirectories that have - been created under <filename>/var/tmp/root</filename> are - empty and should be deleted. The simplest way to do this is - to:</para> - - <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput> -&prompt.root; <userinput>find -d . -type d | xargs rmdir 2>/dev/null</userinput></screen> - - <para>This will remove all empty directories while redirecting - standard error to <filename>/dev/null</filename> to prevent - the warnings about the directories that are not - empty.</para> - - <para><filename>/var/tmp/root</filename> now - contains all the files that should be placed in appropriate - locations below <filename>/</filename>. - Go through each of these files, determining how they differ - from the system's existing files.</para> - - <para>Some of the files installed into - <filename>/var/tmp/root</filename> have a leading - <quote>.</quote>. Make sure to use - <command>ls -a</command> in order to catch them.</para> - - <para>The simplest way to compare files is to use - &man.diff.1;:</para> - - <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen> - - <para>This command will show the differences between the - existing <filename>/etc/shells</filename> and the new - <filename>/var/tmp/root/etc/shells</filename>. Review the - differences to decide whether to merge in custom changes - or to replace the existing file with the new one.</para> - +<!-- +Probably not needed as changes should be minimal and mergemaster does +a good job of merging. <tip> <title>Name the New Root Directory (<filename>/var/tmp/root</filename>) @@ -1946,11 +1881,12 @@ Script started, output file is /var/tmp/ <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen> </tip> + --> </sect2> <sect2 xml:id="make-delete-old"> <info> - <title>Deleting Obsolete Files and Directories</title> + <title>Deleting Obsolete Files and Libraries</title> <authorgroup> <author> @@ -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/ <para>After the <command>make installworld</command> and the subsequent <command>mergemaster</command> have - finished successfully, check for obsolete files and libraries - as follows:</para> + finished successfully, check for obsolete files and libraries:</para> <screen>&prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make check-old</userinput></screen> @@ -1998,11 +1933,6 @@ Script started, output file is /var/tmp/ <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 @@ -2014,10 +1944,6 @@ Script started, output file is /var/tmp/ through <command>yes</command>:</para> <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen> - </sect2> - - <sect2 xml:id="make-delete-old-libs"> - <title>Deleting obsolete libraries</title> <warning> <title>Warning</title> @@ -2031,9 +1957,8 @@ Script started, output file is /var/tmp/ executed.</para> </warning> - <para>Utilities for checking shared library dependencies are - available from the Ports Collection in - <package>sysutils/libchk</package> or + <para>Utilities for checking shared library dependencies include + <package>sysutils/libchk</package> and <package>sysutils/bsdadminscripts</package>.</para> <para>Obsolete shared libraries can conflict with newer @@ -2050,22 +1975,19 @@ Script started, output file is /var/tmp/ &prompt.root; <userinput>pkg which /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. + <para>Then deinstall, rebuild, and reinstall the port. To automate this process, <package>ports-mgmt/portmaster</package> 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:</para> <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen> - <para>You should now have successfully upgraded the &os; - system. Congratulations.</para> - - <para>If things went slightly wrong, it is easy to rebuild a + <para>If something goes wrong, it is easy to rebuild a particular piece of the system. For example, if <filename>/etc/magic</filename> was accidentally deleted as part of the upgrade or merge of <filename>/etc</filename>, - &man.file.1; will stop working. To fix this, run:</para> + <command>file</command> will stop working. To fix this, run:</para> <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput> &prompt.root; <userinput>make all install</userinput></screen>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201405011938.s41Jc4Bx012091>