Date: Thu, 6 Feb 2014 17:20:15 +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: r43806 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201402061720.s16HKFqR036679@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Thu Feb 6 17:20:15 2014 New Revision: 43806 URL: http://svnweb.freebsd.org/changeset/doc/43806 Log: More incorporation of redundant information. Definitely very much a WIP. 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 Feb 6 16:49:50 2014 (r43805) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu Feb 6 17:20:15 2014 (r43806) @@ -1544,6 +1544,18 @@ before running "/usr/sbin/freebsd-update the function of each command.</para> <step> + <para>If the build world process has previously been run on + this system, a copy of the previous build may still exist + in <filename class="directory">/usr/obj</filename>. To speed up the new build world + process, and possibly save some dependency headaches, + remove this directory if it already exists:</para> + + <screen>&prompt.root; <userinput>cd /usr/obj</userinput> +&prompt.root; <userinput>chflags -R noschg *</userinput> +&prompt.root; <userinput>rm -rf *</userinput></screen> + </step> + + <step> <para>Compile the new compiler and a few related tools, then use the new compiler to compile the rest of the new world. The result is saved to @@ -1577,11 +1589,12 @@ before running "/usr/sbin/freebsd-update <screen>&prompt.root; <userinput>shutdown now</userinput></screen> - <para>Once in single-user mode, run this command if the + <para>Once in single-user mode, run these commands if the system is formatted with UFS:</para> <screen>&prompt.root; <userinput>mount -u /</userinput> -&prompt.root; <userinput>mount -a -t ufs</userinput></screen> +&prompt.root; <userinput>mount -a -t ufs</userinput> +&prompt.root; <userinput>swapon -a</userinput></screen> <para>If the system is instead formatted with ZFS, run these two commands. This example assumes a zpool name of @@ -1592,18 +1605,22 @@ before running "/usr/sbin/freebsd-update </step> <step> - <para>Then, for either filesystem, run:</para> + <para>Then, for either file system, if the <acronym>CMOS</acronym> clock is set to local time + (this is true if the output of &man.date.1; does not show + the correct time and zone), run:</para> <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen> </step> <step> - <para>Next, perform some initial configuration file updates - in preparation for the new world. For instance, this step - may add new groups or new system accounts which have been + <para>Next, perform some initial configuration file updates to <filename class="directory">/etc</filename> + in preparation for the new world. The following command compares + only those files that are essential for the success of + <buildtarget>installworld</buildtarget>. For instance, this step + may add new groups, system accounts, or startup scripts which have been added to &os; since the last update. This is necessary so that the <buildtarget>installworld</buildtarget> step will - be able to use the new system accounts and groups.</para> + be able to use any new system accounts, groups, and scripts.</para> <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen> </step> @@ -1646,42 +1663,51 @@ before running "/usr/sbin/freebsd-update <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen> </step> </procedure> + + <indexterm><primary>single-user mode</primary></indexterm> + + <para>If the system can have a window of down-time, consider compiling the system in single user mode instead + of compiling the system in multi-user + mode, and then dropping into single user mode for the + installation. + Reinstalling the system touches a lot of important system + files, all the standard system binaries, libraries, and + include files. Changing these on a running system, + particularly one with active users, is asking for + trouble.</para> </sect2> <sect2 xml:id="src-updating"> - <title>Check <filename>/etc/make.conf</filename></title> + <title>Configuration Files</title> <indexterm> <primary><filename>make.conf</filename></primary> </indexterm> - <para>The following sections clearly describe each step, - especially when using a custom kernel configuration.</para> - <para>Available &man.make.1; options are shown in - &man.make.conf.5; and - <filename>/usr/share/examples/etc/make.conf</filename>. These - settings can be added to <filename>/etc/make.conf</filename> - to control the way &man.make.1; runs and how it builds - programs. Changes to some settings can have far-reaching and - potentially surprising effects. Read the comments in both - locations and keep in mind that the defaults have been chosen - for a combination of performance and safety.</para> + <para>This section describes the configuration files used by the + build world process.</para> - <para>Options set in <filename>/etc/make.conf</filename> take + <para>The options available to &man.make.1; are described in + &man.make.conf.5; and some common examples are included in + <filename>/usr/share/examples/etc/make.conf</filename>. + Any options which are added to <filename>/etc/make.conf</filename> + will control the way &man.make.1; runs and how it builds + programs. Such options take effect every time &man.make.1; is used, including compiling - applications from the Ports Collection or user-written C + applications from the Ports Collection, compiling custom C programs, or building the &os; operating system.</para> - </sect2> - - <sect2 xml:id="src-conf"> - <title>Check <filename>/etc/src.conf</filename></title> + + <para>Changes to some settings can have far-reaching and + potentially surprising effects. Read the comments in both + locations and keep in mind that the defaults have been chosen + for a combination of performance and safety.</para> <indexterm> <primary><filename>src.conf</filename></primary> </indexterm> - <para><filename>/etc/src.conf</filename> controls the building - of the operating system from source code. Unlike + <para>How + the operating system is built from source code is controlled by <filename>/etc/src.conf</filename>. Unlike <filename>/etc/make.conf</filename>, the contents of <filename>/etc/src.conf</filename> only take effect when the &os; operating system itself is being built. Descriptions of @@ -1689,116 +1715,7 @@ before running "/usr/sbin/freebsd-update &man.src.conf.5;. Be cautious about disabling seemingly unneeded kernel modules and build options. Sometimes there are unexpected or subtle interactions.</para> - </sect2> - - <sect2 xml:id="updating-etc"> - <title>Update the Files in <filename>/etc</filename></title> - - <para><filename>/etc</filename> contains a - large part of the system's configuration information, as well - as scripts that are run at system startup. Some of these - scripts change between &os; versions.</para> - - <para>Some of the configuration files are used in the day to - day running of the system, such as - <filename>/etc/group</filename>.</para> - - <para>There have been occasions when the installation part of - <command>make installworld</command> expected certain - usernames or groups to exist. When performing an upgrade, it - is likely that these users or groups do not yet exist. In - some cases <command>make buildworld</command> will check to - see if these users or groups exist.</para> - - <para>The solution is to run &man.mergemaster.8; in - pre-buildworld mode with <option>-p</option>. This compares - only those files that are essential for the success of - <buildtarget>buildworld</buildtarget> or - <buildtarget>installworld</buildtarget>.</para> - - <tip> - <para>To check which files are owned by the group being - renamed or deleted:</para> - - <screen>&prompt.root; <userinput>find / -group GID -print</userinput></screen> - - <para>This command will show all files owned by group - <replaceable>GID</replaceable>, which can be either a group - name or a numeric group ID.</para> - </tip> - </sect2> - - <sect2 xml:id="makeworld-singleuser"> - <title>Drop to Single User Mode</title> - - <indexterm><primary>single-user mode</primary></indexterm> - - <para>Consider compiling the system in single user mode. - Reinstalling the system touches a lot of important system - files, all the standard system binaries, libraries, and - include files. Changing these on a running system, - particularly one with active users, is asking for - trouble.</para> - - <indexterm><primary>multi-user mode</primary></indexterm> - <para>Another method is to compile the system in multi-user - mode, and then drop into single user mode for the - installation. With this method, hold off on the following - steps until the build has completed. Drop to single user mode - in order to run <buildtarget>installkernel</buildtarget> or - <buildtarget>installworld</buildtarget>.</para> - - <para>To enter single user mode from a running system:</para> - - <screen>&prompt.root; <userinput>shutdown now</userinput></screen> - - <para>Alternatively, reboot the system, and at the boot prompt, - select the <quote>single user</quote> option. Once at the - single user mode shell prompt, run:</para> - - <screen>&prompt.root; <userinput>fsck -p</userinput> -&prompt.root; <userinput>mount -u /</userinput> -&prompt.root; <userinput>mount -a -t ufs</userinput> -&prompt.root; <userinput>swapon -a</userinput></screen> - - <para>This checks the file systems, remounts - <filename>/</filename> read/write, mounts all the other UFS - file systems referenced in <filename>/etc/fstab</filename>, - and turns swapping on.</para> - - <note> - <para>If the CMOS clock is set to local time and not to GMT - (this is true if the output of &man.date.1; does not show - the correct time and zone), run the following - command:</para> - - <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen> - - <para>This ensures that the local time-zone settings get set - up correctly.</para> - </note> - </sect2> - - <sect2 xml:id="cleaning-usr-obj"> - <title>Remove <filename>/usr/obj</filename></title> - - <para>As parts of the system are rebuilt, they are, by default, - placed in subdirectories of <filename>/usr/obj</filename>. - The directories shadow those under - <filename>/usr/src</filename>.</para> - - <para>To speed up the <command>make buildworld</command> - process, and possibly save some dependency headaches, - remove this directory if it already exists.</para> - - <para>Some files below <filename>/usr/obj</filename> may have - the immutable flag set which must be removed first using - &man.chflags.1;.</para> - - <screen>&prompt.root; <userinput>cd /usr/obj</userinput> -&prompt.root; <userinput>chflags -R noschg *</userinput> -&prompt.root; <userinput>rm -rf *</userinput></screen> - </sect2> + </sect2> <sect2 xml:id="make-buildworld"> <title>Recompile the Base System</title> @@ -2005,16 +1922,9 @@ Script done, …</screen> problems. See &man.init.8; for details about <varname>kern.securelevel</varname> and &man.chflags.1; for details about the various file flags.</para> - </sect2> - - <sect2 xml:id="new-kernel-singleuser"> - <title>Reboot into Single User Mode</title> - - <indexterm><primary>single-user mode</primary></indexterm> <para>Reboot into single user mode to test that the new kernel - works using the instructions in - <xref linkend="makeworld-singleuser"/>.</para> + works.</para> </sect2> <sect2 xml:id="make-installworld"> @@ -2160,11 +2070,6 @@ Script done, …</screen> <filename>/etc</filename> are not in <filename>/usr/src/etc</filename>.</para> - <para>If you are using &man.mergemaster.8; (as recommended), - you can skip forward to the - <link linkend="updating-upgrading-rebooting">next - section</link>.</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> @@ -2376,15 +2281,6 @@ Script done, …</screen> <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen> </sect2> - <sect2 xml:id="updating-upgrading-rebooting"> - <title>Rebooting</title> - - <para>Verify that everything appears to be in the right place, - then reboot the system using &man.shutdown.8;:</para> - - <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> - </sect2> - <sect2 xml:id="make-delete-old-libs"> <title>Deleting obsolete libraries</title> @@ -2607,10 +2503,10 @@ Building everything.. </varlistentry> <varlistentry> - <term>What do I do if something goes wrong?</term> + <term>What if something goes wrong?</term> <listitem> - <para>Make absolutely sure that the environment has no + <para>First, make absolutely sure that the environment has no extraneous cruft from earlier builds:</para> <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402061720.s16HKFqR036679>