svn commit: r44736 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Dru Lavigne
dru at FreeBSD.org
Thu May 1 20:09:55 UTC 2014
Author: dru
Date: Thu May 1 20:09:54 2014
New Revision: 44736
URL: http://svnweb.freebsd.org/changeset/doc/44736
Log:
White space fix only. Translators can ignore.
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 19:38:04 2014 (r44735)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu May 1 20:09:54 2014 (r44736)
@@ -176,11 +176,11 @@
the release. Release announcements are available from <uri
xlink:href="http://www.FreeBSD.org/releases/">http://www.FreeBSD.org/releases/</uri>.</para>
- <note>
- <para>If a <command>crontab</command> utilizing the features
- of &man.freebsd-update.8; exists, it must be disabled before
- upgrading the operating system.</para>
- </note>
+ <note>
+ <para>If a <command>crontab</command> utilizing the features of
+ &man.freebsd-update.8; exists, it must be disabled before
+ upgrading the operating system.</para>
+ </note>
<para>This section describes the configuration file used by
<command>freebsd-update</command>, demonstrates how to apply a
@@ -246,9 +246,9 @@ MergeChanges /etc/ /var/named/etc/ /boot
similar to &man.mergemaster.8;, but with fewer options.
Merges are either accepted, open an editor, or cause
<command>freebsd-update</command> to abort. When in doubt,
- backup <filename>/etc</filename> and just
- accept the merges. See <xref linkend="mergemaster"/> for more
- information about <command>mergemaster</command>.</para>
+ backup <filename>/etc</filename> and just accept the merges.
+ See <xref linkend="mergemaster"/> for more information about
+ <command>mergemaster</command>.</para>
<programlisting># Directory in which to store downloaded updates and temporary
# files used by &os; Update.
@@ -1276,11 +1276,11 @@ before running "/usr/sbin/freebsd-update
verify, and apply the changes to the user's copy of the sources.
This process is more efficient than
<application>Subversion</application> and places less strain on
- server resources since it is a <emphasis>push</emphasis>
- rather than a <emphasis>pull</emphasis> model.</para>
+ server resources since it is a <emphasis>push</emphasis> rather
+ than a <emphasis>pull</emphasis> model.</para>
- <para>There are other trade-offs. If a user inadvertently
- wipes out portions of the local archive,
+ <para>There are other trade-offs. If a user inadvertently wipes
+ out portions of the local archive,
<application>Subversion</application> will detect and rebuild
the damaged portions. <application>CTM</application> will not
do this, and if a user deletes some portion of the source tree
@@ -1333,29 +1333,29 @@ before running "/usr/sbin/freebsd-update
<step>
<para>Read <filename>/usr/src/UPDATING</filename> for any
- extra steps necessary for that version of the
- source. This file contains important information about
- potential problems and may specify the order to run certain
- commands. Many upgrades require specific additional steps
- such as renaming or deleting specific files prior to
- installing the new world. These will be listed at the end of this file
- where the currently recommended upgrade sequence is
- explicitly spelled out. If
- <filename>UPDATING</filename> contradicts any steps in this
- chapter, the instructions in <filename>UPDATING</filename>
- take precedence and should be followed.</para>
+ extra steps necessary for that version of the source. This
+ file contains important information about potential problems
+ and may specify the order to run certain commands. Many
+ upgrades require specific additional steps such as renaming
+ or deleting specific files prior to installing the new
+ world. These will be listed at the end of this file where
+ the currently recommended upgrade sequence is explicitly
+ spelled out. If <filename>UPDATING</filename> contradicts
+ any steps in this chapter, the instructions in
+ <filename>UPDATING</filename> take precedence and should be
+ followed.</para>
</step>
</procedure>
<warning>
<title>Do Not Use <command>make world</command></title>
- <para>Some older documentation recommends using
- <command>make world</command>. However, that command skips
- some important steps and should only be used by experts. For
- almost all circumstances <command>make world</command> is the
- wrong thing to do, and the procedure described here should be
- used instead.</para>
+ <para>Some older documentation recommends using <command>make
+ world</command>. However, that command skips some important
+ steps and should only be used by experts. For almost all
+ circumstances <command>make world</command> is the wrong thing
+ to do, and the procedure described here should be used
+ instead.</para>
</warning>
<sect2 xml:id="canonical-build">
@@ -1363,8 +1363,8 @@ before running "/usr/sbin/freebsd-update
<para>The build world process assumes an upgrade from an older
&os; version using the source of a newer version that was
- obtained using the instructions in
- <xref linkend="synching"/>.</para>
+ obtained using the instructions in <xref
+ linkend="synching"/>.</para>
<para>In &os;, the term <quote>world</quote> includes the
kernel, core system binaries, libraries, programming files,
@@ -1393,25 +1393,25 @@ before running "/usr/sbin/freebsd-update
step to do so.</para>
<para>These concerns have led to the recommended upgrade
- sequence described in
- the following procedure.</para>
+ sequence described in the following procedure.</para>
<note>
- <para>It is a good idea to save the output from running
- <command>make</command> to a file. If something goes wrong, a copy of
- the error message can be posted to one of the &os; mailing
- lists.</para>
-
- <para>The easiest way to do this is to use <command>script</command> with a
- parameter that specifies the name of the file to save all
- output to. Do not save the output to
- <filename>/tmp</filename> as this directory may be cleared at
- next reboot. A better place to save the file is
- <filename>/var/tmp</filename>. Run this command immediately before rebuilding
- the world, and then type <userinput>exit</userinput> when the
- process has finished:</para>
+ <para>It is a good idea to save the output from running
+ <command>make</command> to a file. If something goes wrong,
+ a copy of the error message can be posted to one of the &os;
+ mailing lists.</para>
+
+ <para>The easiest way to do this is to use
+ <command>script</command> with a parameter that specifies
+ the name of the file to save all output to. Do not save the
+ output to <filename>/tmp</filename> as this directory may be
+ cleared at next reboot. A better place to save the file is
+ <filename>/var/tmp</filename>. Run this command immediately
+ before rebuilding the world, and then type
+ <userinput>exit</userinput> when the process has
+ finished:</para>
- <screen>&prompt.root; <userinput>script <replaceable>/var/tmp/mw.out</replaceable></userinput>
+ <screen>&prompt.root; <userinput>script <replaceable>/var/tmp/mw.out</replaceable></userinput>
Script started, output file is /var/tmp/mw.out</screen>
</note>
@@ -1519,16 +1519,16 @@ Script started, output file is /var/tmp/
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 any new system accounts, groups, and
- scripts. Refer to <xref linkend="mergemaster"/> for more
- detailed instructions about this command:</para>
+ to use any new system accounts, groups, and scripts.
+ Refer to <xref linkend="mergemaster"/> for more detailed
+ instructions about this command:</para>
<screen>&prompt.root; <userinput>mergemaster -p</userinput></screen>
</step>
<step>
- <para>Install the new world and system binaries from <filename
- class="directory">/usr/obj</filename>.</para>
+ <para>Install the new world and system binaries from
+ <filename class="directory">/usr/obj</filename>.</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>make installworld</userinput></screen>
@@ -1588,22 +1588,25 @@ Script started, output file is /var/tmp/
<para>This build world process uses several configuration
files.</para>
- <para>The <filename>Makefile</filename> located in <filename>/usr/src</filename>
- describes how the programs that comprise &os; should be
- built and the order in which they should be built.</para>
-
- <para>The options available to <command>make</command> are described in
- &man.make.conf.5; and some common examples are included in
+ <para>The <filename>Makefile</filename> located in
+ <filename>/usr/src</filename> describes how the programs that
+ comprise &os; should be built and the order in which they
+ should be built.</para>
+
+ <para>The options available to <command>make</command> 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 how <command>make</command> runs and builds
- programs. These options take effect every time <command>make</command> is
- used, including compiling applications from the Ports
- Collection, compiling custom C programs, or building the &os;
- operating system. 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>
+ programs. These options take effect every time
+ <command>make</command> is used, including compiling
+ applications from the Ports Collection, compiling custom C
+ programs, or building the &os; operating system. 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>
@@ -1630,17 +1633,17 @@ Script started, output file is /var/tmp/
<para>In this example,
<option>-<replaceable>x</replaceable></option> is an option
- passed to <command>make</command>. Refer to &man.make.1; for examples
- of the available options.</para>
+ passed to <command>make</command>. Refer to &man.make.1; for
+ examples of the available options.</para>
- <para>To pass a variable, specify the variable name with <option>-D<replaceable>VARIABLE</replaceable></option>.
- The
+ <para>To pass a variable, specify the variable name with
+ <option>-D<replaceable>VARIABLE</replaceable></option>. The
behavior of the <filename>Makefile</filename> is controlled by
variables. These can either be set in
<filename>/etc/make.conf</filename> or they can be specified
when using <command>make</command>. For example, this
- variable specifies that profiled libraries
- should not be built:</para>
+ variable specifies that profiled libraries should not be
+ built:</para>
<screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen>
@@ -1649,43 +1652,43 @@ Script started, output file is /var/tmp/
<programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting>
- <para>The <replaceable>target</replaceable> tells <command>make</command> what
- to do and the <filename>Makefile</filename> defines the
- available targets. Some targets
- are used by the build process to break out the steps
- necessary to rebuild the system into a number of
+ <para>The <replaceable>target</replaceable> tells
+ <command>make</command> what to do and the
+ <filename>Makefile</filename> defines the available targets.
+ Some targets are used by the build process to break out the
+ steps necessary to rebuild the system into a number of
sub-steps.</para>
<para>Having separate options is useful for two reasons. First,
- it allows for a build that does not
- affect any components of a running system. Because of this,
- <buildtarget>buildworld</buildtarget> can be safely run on a machine
- running in multi-user mode. It is
- still recommended that <buildtarget>installworld</buildtarget>
- be run in part in single-user mode, though.</para>
-
- <para>Secondly, it allows <acronym>NFS</acronym> mounts to be used to upgrade
- multiple machines on a network, as described in <xref
- linkend="small-lan"/>.</para>
+ it allows for a build that does not affect any components of a
+ running system. Because of this,
+ <buildtarget>buildworld</buildtarget> can be safely run on a
+ machine running in multi-user mode. It is still recommended
+ that <buildtarget>installworld</buildtarget> be run in part in
+ single-user mode, though.</para>
+
+ <para>Secondly, it allows <acronym>NFS</acronym> mounts to be
+ used to upgrade multiple machines on a network, as described
+ in <xref linkend="small-lan"/>.</para>
<para>It is possible to specify <option>-j</option> which will
cause <command>make</command> to spawn several simultaneous
- processes.
- Since much of the compiling process is <acronym>I/O</acronym>-bound
- rather than <acronym>CPU</acronym>-bound, this is useful on both single <acronym>CPU</acronym>
- and multi-<acronym>CPU</acronym> machines.</para>
-
- <para>On a single-<acronym>CPU</acronym> machine, run
- the following command to have up to 4 processes running at
- any one time. Empirical evidence posted to the mailing lists
- shows this generally gives the best performance
- benefit.</para>
+ processes. Since much of the compiling process is
+ <acronym>I/O</acronym>-bound rather than
+ <acronym>CPU</acronym>-bound, this is useful on both single
+ <acronym>CPU</acronym> and multi-<acronym>CPU</acronym>
+ machines.</para>
+
+ <para>On a single-<acronym>CPU</acronym> machine, run the
+ following command to have up to 4 processes running at any one
+ time. Empirical evidence posted to the mailing lists shows
+ this generally gives the best performance benefit.</para>
<screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen>
- <para>On a multi-<acronym>CPU</acronym> machine, try
- values between <literal>6</literal> and <literal>10</literal> to see how they speed things
- up.</para>
+ <para>On a multi-<acronym>CPU</acronym> machine, try values
+ between <literal>6</literal> and <literal>10</literal> to see
+ how they speed things up.</para>
<indexterm>
<primary>rebuilding <quote>world</quote></primary>
@@ -1693,11 +1696,11 @@ Script started, output file is /var/tmp/
</indexterm>
<note>
- <para>If any variables were specified to
- <command>make buildworld</command>, specify the same
- variables to <command>make installworld</command>. However,
- <option>-j</option> must <emphasis>never</emphasis> be used with
- <buildtarget>installworld</buildtarget>.</para>
+ <para>If any variables were specified to <command>make
+ buildworld</command>, specify the same variables to
+ <command>make installworld</command>. However,
+ <option>-j</option> must <emphasis>never</emphasis> be used
+ with <buildtarget>installworld</buildtarget>.</para>
<para>For example, if this command was used:</para>
@@ -1707,15 +1710,15 @@ Script started, output file is /var/tmp/
<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
- <para>Otherwise, the second command will try to install profiled
- libraries that were not built during the
+ <para>Otherwise, the second command will try to install
+ profiled libraries that were not built during the
<command>make buildworld</command> phase.</para>
</note>
</sect2>
- <sect2 xml:id="mergemaster">
- <info>
- <title>Merging Configuration Files</title>
+ <sect2 xml:id="mergemaster">
+ <info>
+ <title>Merging Configuration Files</title>
<authorgroup>
<author>
@@ -1734,73 +1737,71 @@ Script started, output file is /var/tmp/
</primary>
</indexterm>
- <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
- <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>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
- how file differences are
- shown.</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
- <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
- <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>
-
- <para>Choosing to install the unmodified temporary file will
- replace the current file with the new one. For most
- unmodified files, this is the best option.</para>
-
- <para>Choosing to merge the file will present a text editor,
- and the contents of both files. The files can be merged
- by reviewing both files side by side on the screen, and
- choosing parts from both to create a finished product. When
- the files are compared side by side, <keycap>l</keycap>
- selects the left contents and <keycap>r</keycap> selects
- contents from the right. The final output will be a file
- consisting of both parts, which can then be installed. This
- option is customarily used for files where settings have
- been modified by the user.</para>
-
- <para>Choosing to view the results again will
- redisplay the file differences.</para>
-
- <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>&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
+ <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>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 how file differences are shown.</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
+ <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 <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>
+
+ <para>Choosing to install the unmodified temporary file will
+ replace the current file with the new one. For most
+ unmodified files, this is the best option.</para>
+
+ <para>Choosing to merge the file will present a text editor, and
+ the contents of both files. The files can be merged by
+ reviewing both files side by side on the screen, and choosing
+ parts from both to create a finished product. When the files
+ are compared side by side, <keycap>l</keycap> selects the left
+ contents and <keycap>r</keycap> selects contents from the
+ right. The final output will be a file consisting of both
+ parts, which can then be installed. This option is
+ customarily used for files where settings have been modified
+ by the user.</para>
+
+ <para>Choosing to view the results again will redisplay the file
+ differences.</para>
+
+ <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>
<!--
Probably not needed as changes should be minimal and mergemaster does
a good job of merging.
@@ -1920,10 +1921,9 @@ a good job of merging.
following instructions should be used to remove obsolete files
during the system upgrade process.</para>
- <para>After the
- <command>make installworld</command>
- and the subsequent <command>mergemaster</command> have
- finished successfully, check for obsolete files and libraries:</para>
+ <para>After the <command>make installworld</command> and the
+ subsequent <command>mergemaster</command> have 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>
@@ -1952,8 +1952,7 @@ a good job of merging.
still depend on those obsolete files. This is especially
true for old libraries. In most cases, the programs, ports,
or libraries that used the old library need to be recompiled
- before <command>make
- delete-old-libs</command> is
+ before <command>make delete-old-libs</command> is
executed.</para>
</warning>
@@ -1975,11 +1974,11 @@ a good job of merging.
&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. To automate this process,
- <package>ports-mgmt/portmaster</package> can
- be used. After all ports are rebuilt
- and no longer use the old libraries, delete the old libraries
- using the following command:</para>
+ <para>Then deinstall, rebuild, and reinstall the port. To
+ automate this process,
+ <package>ports-mgmt/portmaster</package> can 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>
@@ -1987,7 +1986,8 @@ a good job of merging.
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>,
- <command>file</command> 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>
@@ -2209,79 +2209,77 @@ Building everything..
</indexterm>
<para>When multiple machines need to track the same source tree,
- it is a waste of disk space, network bandwidth, and <acronym>CPU</acronym> cycles
- to have each system download the sources and rebuild everything.
- The solution is to have one machine do most of the work, while
- the rest of the machines mount that work via <acronym>NFS</acronym>. This section
+ it is a waste of disk space, network bandwidth, and
+ <acronym>CPU</acronym> cycles to have each system download the
+ sources and rebuild everything. The solution is to have one
+ machine do most of the work, while the rest of the machines
+ mount that work via <acronym>NFS</acronym>. This section
outlines a method of doing so. For more information about using
<acronym>NFS</acronym>, refer to <xref
linkend="network-nfs"/>.</para>
- <para>First, identify a set of machines which will run the same
- set of binaries, known as a <firstterm>build set</firstterm>.
- Each machine can have a custom kernel, but will run the same
- userland binaries. From that set, choose a machine to be the
- <firstterm>build machine</firstterm> that the world and kernel
- are built on. Ideally, this is a fast machine that has
- sufficient spare <acronym>CPU</acronym> to run <command>make buildworld</command>
- and <command>make buildkernel</command>.</para>
-
- <para>Select a machine to
- be the <firstterm>test machine</firstterm>, which will test
- software updates before they are put into production. This
- <emphasis>must</emphasis> be a machine that can afford to be
- down for an extended period of time. It can be the build
- machine, but need not be.</para>
-
- <para>All the machines in this build set need to mount
- <filename>/usr/obj</filename> and
- <filename>/usr/src</filename> from the build machine via
- <acronym>NFS</acronym>. For multiple build sets,
- <filename>/usr/src</filename> should be on one build machine,
- and <acronym>NFS</acronym> mounted on the rest.</para>
-
- <para>Ensure that <filename>/etc/make.conf</filename>
- and <filename>/etc/src.conf</filename> on all the machines in
- the build set agree with the build machine. That means that
- the build machine must build all the parts of the base system
- that any machine in the build set is going to install. Also,
- each build machine should have its kernel name set with
- <varname>KERNCONF</varname> in
- <filename>/etc/make.conf</filename>, and the build machine
- should list them all in its <varname>KERNCONF</varname>, listing
- its own kernel first. The build machine must have the kernel
- configuration files for each machine in its <filename
- class="directory">/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>.</para>
-
- <para>On the build machine, build the kernel and world as
- described in <xref linkend="makeworld"/>, but do not
- install anything on the build machine. Instead, install the built kernel
- on the test machine. On the test machine, mount
- <filename>/usr/src</filename> and
- <filename>/usr/obj</filename> via <acronym>NFS</acronym>. Then, run
- <command>shutdown now</command> to go to single-user mode in order to
- install the new kernel and world and run
- <command>mergemaster</command> as usual. When done, reboot to
- return to normal multi-user operations.</para>
-
- <para>After verifying that everything on the test machine is
- working properly, use the same procedure to install the new
- software on each of the other machines in the build
- set.</para>
-
- <para>The same methodology can be used for the ports tree. The first
- step is to share <filename>/usr/ports</filename> via
- <acronym>NFS</acronym> to all the machines in the build set. To
- configure <filename>/etc/make.conf</filename> to
- share distfiles, set <varname>DISTDIR</varname> to a common
- shared directory that is writable by whichever user
- <systemitem class="username">root</systemitem> is mapped to by
- the <acronym>NFS</acronym> mount. Each machine should set
- <varname>WRKDIRPREFIX</varname> to a local build directory, if
- ports are to be built locally.
- Alternately, if the build system is to build and distribute
- packages to the machines in the build set,
- set <varname>PACKAGES</varname> on the build system to a directory similar to
- <varname>DISTDIR</varname>.</para>
+ <para>First, identify a set of machines which will run the same
+ set of binaries, known as a <firstterm>build set</firstterm>.
+ Each machine can have a custom kernel, but will run the same
+ userland binaries. From that set, choose a machine to be the
+ <firstterm>build machine</firstterm> that the world and kernel
+ are built on. Ideally, this is a fast machine that has
+ sufficient spare <acronym>CPU</acronym> to run <command>make
+ buildworld</command> and <command>make
+ buildkernel</command>.</para>
+
+ <para>Select a machine to be the <firstterm>test
+ machine</firstterm>, which will test software updates before
+ they are put into production. This <emphasis>must</emphasis> be
+ a machine that can afford to be down for an extended period of
+ time. It can be the build machine, but need not be.</para>
+
+ <para>All the machines in this build set need to mount
+ <filename>/usr/obj</filename> and <filename>/usr/src</filename>
+ from the build machine via <acronym>NFS</acronym>. For multiple
+ build sets, <filename>/usr/src</filename> should be on one build
+ machine, and <acronym>NFS</acronym> mounted on the rest.</para>
+
+ <para>Ensure that <filename>/etc/make.conf</filename> and
+ <filename>/etc/src.conf</filename> on all the machines in the
+ build set agree with the build machine. That means that the
+ build machine must build all the parts of the base system that
+ any machine in the build set is going to install. Also, each
+ build machine should have its kernel name set with
+ <varname>KERNCONF</varname> in
+ <filename>/etc/make.conf</filename>, and the build machine
+ should list them all in its <varname>KERNCONF</varname>,
+ listing its own kernel first. The build machine must have the
+ kernel configuration files for each machine in its <filename
+ class="directory">/usr/src/sys/<replaceable>arch</replaceable>/conf</filename>.</para>
+
+ <para>On the build machine, build the kernel and world as
+ described in <xref linkend="makeworld"/>, but do not install
+ anything on the build machine. Instead, install the built
+ kernel on the test machine. On the test machine, mount
+ <filename>/usr/src</filename> and
+ <filename>/usr/obj</filename> via <acronym>NFS</acronym>. Then,
+ run <command>shutdown now</command> to go to single-user mode in
+ order to install the new kernel and world and run
+ <command>mergemaster</command> as usual. When done, reboot to
+ return to normal multi-user operations.</para>
+
+ <para>After verifying that everything on the test machine is
+ working properly, use the same procedure to install the new
+ software on each of the other machines in the build set.</para>
+
+ <para>The same methodology can be used for the ports tree. The
+ first step is to share <filename>/usr/ports</filename> via
+ <acronym>NFS</acronym> to all the machines in the build set. To
+ configure <filename>/etc/make.conf</filename> to share
+ distfiles, set <varname>DISTDIR</varname> to a common shared
+ directory that is writable by whichever user <systemitem
+ class="username">root</systemitem> is mapped to by the
+ <acronym>NFS</acronym> mount. Each machine should set
+ <varname>WRKDIRPREFIX</varname> to a local build directory, if
+ ports are to be built locally. Alternately, if the build system
+ is to build and distribute packages to the machines in the build
+ set, set <varname>PACKAGES</varname> on the build system to a
+ directory similar to <varname>DISTDIR</varname>.</para>
</sect1>
</chapter>
More information about the svn-doc-all
mailing list