Date: Thu, 6 Feb 2014 01:40:32 +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: r43796 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201402060140.s161eWrk056368@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Thu Feb 6 01:40:32 2014 New Revision: 43796 URL: http://svnweb.freebsd.org/changeset/doc/43796 Log: All the required steps are now in order, in one place, and in a Procedure. Next round will improve the flow of the next subsection. 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 00:22:35 2014 (r43795) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu Feb 6 01:40:32 2014 (r43796) @@ -1500,11 +1500,11 @@ before running "/usr/sbin/freebsd-update <title>Overview of Process</title> <para>The build world process assumes an upgrade from an older &os; - version using the sources to a newer - version that were obtained using the instructions in + version using the source of a newer + version that was obtained using the instructions in <xref linkend="synching"/>.</para> - <para><quote>World</quote> includes the &os; kernel, core system binaries, + <para>In &os;, the term <quote>world</quote> includes the kernel, core system binaries, libraries, programming files, and built-in compiler. The order in which these components are built and installed is important.</para> @@ -1522,13 +1522,13 @@ before running "/usr/sbin/freebsd-update <para>Some configuration changes must be made before the new world is installed, but others might break the old world. Hence, two different configuration upgrade steps are - generally needed. For the most part, the update process only replaces or - adds files and existing old files are not deleted. In a - few cases, this can cause problems. As a result, the - update procedure will sometimes specify certain files that - should be manually deleted at certain steps.</para> + used. For the most part, the update process only replaces or + adds files and existing old files are not deleted. Since + this can cause problems, <filename>/usr/src/UPDATING</filename> + will indicate if any files + need to be manually deleted and at which step to do so.</para> - <para>These concerns have led to the following recommended upgrade + <para>These concerns have led to the recommended upgrade sequence described in the following procedure.</para> @@ -1537,169 +1537,110 @@ before running "/usr/sbin/freebsd-update <para>The commands used in the build world process should be run in the order specified here. This section summarizes the function of each command.</para> - <step> - <para><command>make - buildworld</command></para> - - <para>This first compiles the new compiler and a few related - tools, then uses the new compiler to compile the rest of - the new world. The result ends up in - <filename>/usr/obj</filename>.</para> + + <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 + <filename class="directory">/usr/obj</filename>.</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make buildworld</userinput></screen> </step> <step> - <para><command>make - buildkernel</command></para> + <para>Use the new compiler + residing in <filename class="directory">/usr/obj</filename> + to build the new kernel, in order to + protect against compiler-kernel mismatches:</para> - <para>This uses the <emphasis>new</emphasis> compiler - residing in <filename>/usr/obj</filename> in order to - protect against compiler-kernel mismatches.</para> + <screen>&prompt.root; <userinput>make buildkernel</userinput></screen> </step> <step> - <para><command>make - installkernel</command></para> - - <para>Place the new kernel and kernel modules onto the disk, + <para>Install the new kernel and kernel modules, making it possible to boot with the newly updated - kernel.</para> + kernel:</para> + + <screen>&prompt.root; <userinput>make installkernel</userinput></screen> </step> <step> - <para>Reboot into single user mode.</para> - - <para>Single user mode minimizes problems from updating - software that is already running. It also minimizes any + <para>Drop the system into single user mode in order to minimize problems from updating + any binaries that are already running. It also minimizes any problems from running the old world on a new kernel.</para> - </step> - <step> - <para><command>mergemaster - -p</command></para> + <screen>&prompt.root; <userinput>shutdown now</userinput></screen> + + <para>Once in single-user mode, run this command if the + system is formatted with UFS:</para> + + <screen>&prompt.root; <userinput>mount -u /</userinput> +&prompt.root; <userinput>mount -a -t ufs</userinput></screen> - <para>This does some initial configuration file updates in - preparation for the new world. For instance, it may add - new user groups to the system, or new user names to the - password database. This is often necessary when new - groups or special system-user accounts have been added - since the last update, so that the + <para>If the system is instead formatted with ZFS, run these + two commands. This example assumes a zpool name of <literal>zroot</literal>:</para> + + <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput> +&prompt.root; <userinput>zfs mount -a</userinput></screen> + </step> + + <step> + <para>Then, for either filesystem, 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 added + to &os; since the last update. This is necessary so that the <buildtarget>installworld</buildtarget> step will be able - to use the newly installed system user or system group - names without problems.</para> + to use the new system accounts and groups.</para> + + <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen> </step> <step> - <para><command>make - installworld</command></para> + <para>Install the new world + from <filename class="directory">/usr/obj</filename>.</para> - <para>Copies the world - from <filename>/usr/obj</filename>. The - new kernel and new world are now installed on disk.</para> + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make installworld</userinput></screen> </step> <step> - <para><command>mergemaster</command></para> + <para>Update any remaining configuration files.</para> - <para>Repeated to update the remaining configuration files, - now that the new world is on disk.</para> + <screen>&prompt.root; <userinput>mergemaster -p</userinput></screen> </step> <step> - <para><command>make - delete-old</command></para> + <para>Delete any obsolete files. This is + important as they may cause problems if left on + the disk.</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> + <screen>&prompt.root; <userinput>make delete-old</userinput></screen> </step> <step> - <para>Reboot.</para> + <para>A full reboot is now needed to load the new + kernel and new world with the new configuration files.</para> - <para>A full machine reboot is needed now to load the new - kernel and new world with new configuration files.</para> + <screen>&prompt.root; <userinput>reboot</userinput></screen> </step> <step> - <para><command>make - delete-old-libs</command></para> + <para>Make sure that all installed ports have first been 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> - <para>Remove any obsolete libraries to avoid conflicts with - newer ones. Make sure that all ports have been rebuilt - before old libraries are removed.</para> + <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen> </step> </procedure> - - <para>Upgrades from one release of the same &os; branch to a - more recent release of the same branch, such as from 9.0 to - 9.1, may not need this procedure since it is less likely to - run into serious mismatches between compiler, kernel, - userland, and configuration files. The approach of - <command>make world</command> - followed by building and installing a new kernel might work - well enough for minor updates.</para> - - <para>When upgrading across major releases, people who do not - follow this procedure should expect some problems.</para> - - <para>This procedure has evolved over time as the developers - have found it impossible to completely prevent certain kinds - of mismatch problems. Hopefully, the current procedure will - remain stable for a long time.</para> - - <para>To summarize, the currently recommended way of upgrading - &os; from sources is:</para> - - <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make buildworld</userinput> -&prompt.root; <userinput>make buildkernel</userinput> -&prompt.root; <userinput>make installkernel</userinput> -&prompt.root; <userinput>shutdown -r now</userinput></screen> - - <note> - <para>There are a few rare cases when an extra run of - <command>mergemaster -p</command> is needed before the - <buildtarget>buildworld</buildtarget> step. These are - described in <filename>UPDATING</filename>. In general, - though, this step can safely be omitted when not updating - across one or more major &os; versions.</para> - </note> - - <para>After <buildtarget>installkernel</buildtarget> finishes - successfully, boot into single user mode using <command>boot - -s</command> from the loader prompt.</para> - - <para>If using UFS, run:</para> - - <screen>&prompt.root; <userinput>mount -u /</userinput> -&prompt.root; <userinput>mount -a -t ufs</userinput></screen> - - <para>If using ZFS(assuming a zpool name of zroot), run:</para> - - <screen>&prompt.root; <userinput>zfs set readonly=off zroot</userinput> -&prompt.root; <userinput>zfs mount -a</userinput></screen> - - <para>Then run:</para> - - <screen>&prompt.root; <userinput>adjkerntz -i</userinput> -&prompt.root; <userinput>mergemaster -p</userinput> -&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make installworld</userinput> -&prompt.root; <userinput>mergemaster</userinput> -&prompt.root; <userinput>make delete-old</userinput> -&prompt.root; <userinput>reboot</userinput> -&prompt.root; <userinput>make delete-old-libs</userinput></screen> - - <warning> - <title>Read Further Explanations</title> - - <para>The following sections clearly describe each step, - especially when using a custom kernel configuration.</para> - </warning> </sect2> <sect2 xml:id="src-updating"> @@ -1709,6 +1650,8 @@ before running "/usr/sbin/freebsd-update <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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201402060140.s161eWrk056368>