Date: Mon, 28 Apr 2014 17:39:39 +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: r44674 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201404281739.s3SHdd8W053879@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: dru Date: Mon Apr 28 17:39:38 2014 New Revision: 44674 URL: http://svnweb.freebsd.org/changeset/doc/44674 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 Mon Apr 28 16:19:09 2014 (r44673) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Mon Apr 28 17:39:38 2014 (r44674) @@ -423,7 +423,8 @@ MergeChanges /etc/ /var/named/etc/ /boot &prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput> &prompt.root; <userinput>./install.sh GENERIC</userinput></screen> - <para>Replace <filename class="directory"><replaceable>X.Y-RELEASE</replaceable></filename> + <para>Replace <filename + class="directory"><replaceable>X.Y-RELEASE</replaceable></filename> with the actual version of the release being used. The <filename>GENERIC</filename> kernel will be installed in <filename>/boot/GENERIC</filename> by @@ -717,35 +718,35 @@ before running "/usr/sbin/freebsd-update <para>Documentation is an integral part of the &os; operating system. While an up-to-date version of the &os; documentation - is always available on the &os; web site - (<link xlink:href="&url.base;/doc/">http://www.freebsd.org/doc/</link>), + is always available on the &os; web site (<link + xlink:href="&url.base;/doc/">http://www.freebsd.org/doc/</link>), it can be handy to have an up-to-date, local copy of the &os; website, handbooks, <acronym>FAQ</acronym>, and articles.</para> - + <para>This section describes how to use either source or the &os; Ports Collection to keep a local copy of the &os; documentation up-to-date.</para> - <para>For information on editing and submitting corrections to - the documentation, refer to the &os; Documentation - Project Primer for New Contributors - (<link xlink:href="&url.books.fdp-primer;">http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/</link>).</para>; + <para>For information on editing and submitting corrections to the + documentation, refer to the &os; Documentation Project Primer + for New Contributors (<link + xlink:href="&url.books.fdp-primer;">http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/</link>).</para>; <sect2 xml:id="updating-installed-documentation"> <title>Updating Documentation from Source</title> <para>Rebuilding the &os; documentation from source requires a - collection of tools which are not part of the &os; base system. - The required tools, including + collection of tools which are not part of the &os; base + system. The required tools, including <application>svn</application>, can be installed from the - <package>textproc/docproj</package> package or port - developed by the &os; Documentation Project.</para> + <package>textproc/docproj</package> package or port developed + by the &os; Documentation Project.</para> <para>Once installed, use <application>svn</application> to fetch a clean copy of the documentation source. Replace <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>; - with the address of the closest geographic mirror from - <xref linkend="svn-mirrors"/>:</para> + with the address of the closest geographic mirror from <xref + linkend="svn-mirrors"/>:</para> <screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/doc/head /usr/doc</userinput></screen> @@ -775,10 +776,9 @@ before running "/usr/sbin/freebsd-update <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput> &prompt.root; <userinput>make install clean</userinput></screen> - <para>An alternative way of - updating the documentation is to run this - command from <filename>/usr/doc</filename> or - the desired language-specific subdirectory:</para> + <para>An alternative way of updating the documentation is to run + this command from <filename>/usr/doc</filename> or the desired + language-specific subdirectory:</para> <screen>&prompt.root; <userinput>make update</userinput></screen> @@ -788,11 +788,12 @@ before running "/usr/sbin/freebsd-update <screen>&prompt.root; <userinput>cd /usr/doc</userinput> &prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen> - <para>Several options are available to ease the process of updating - only parts of the documentation, or the build of specific - translations. These options can be set either as system-wide - options in <filename>/etc/make.conf</filename>, or as - command-line options passed to <command>make</command>.</para> + <para>Several options are available to ease the process of + updating only parts of the documentation, or the build of + specific translations. These options can be set either as + system-wide options in <filename>/etc/make.conf</filename>, or + as command-line options passed to + <command>make</command>.</para> <para>The options include:</para> @@ -814,8 +815,8 @@ before running "/usr/sbin/freebsd-update <para>A single format or a list of output formats to be built. Currently, <literal>html</literal>, <literal>html-split</literal>, <literal>txt</literal>, - <literal>ps</literal>, and <literal>pdf</literal> - are supported.</para> + <literal>ps</literal>, and <literal>pdf</literal> are + supported.</para> </listitem> </varlistentry> @@ -859,138 +860,134 @@ before running "/usr/sbin/freebsd-update </indexterm> <para>The previous section presented a method for updating the - &os; documentation from sources. This section describes an alternative method which - uses the Ports Collection and makes it possible to:</para> + &os; documentation from sources. This section describes an + alternative method which uses the Ports Collection and makes + it possible to:</para> <itemizedlist> <listitem> - <para>Install pre-built packages of the - documentation, without having to locally build anything - or install the documentation toolchain.</para> + <para>Install pre-built packages of the documentation, + without having to locally build anything or install the + documentation toolchain.</para> </listitem> <listitem> - <para>Build the documentation sources - through the ports framework, making the checkout and build - steps a bit easier.</para> + <para>Build the documentation sources through the ports + framework, making the checkout and build steps a bit + easier.</para> </listitem> </itemizedlist> <para>This method of updating the &os; documentation is - supported by a set of - documentation ports and packages which are updated by the - &a.doceng; on a monthly basis. These are listed in the &os; - Ports Collection, under the docs category (<link + supported by a set of documentation ports and packages which + are updated by the &a.doceng; on a monthly basis. These are + listed in the &os; Ports Collection, under the docs + category (<link xlink:href="http://www.freshports.org/docs/">http://www.freshports.org/docs/</link>).</para>; - <para>Organization of the documentation ports is as - follows:</para> + <para>Organization of the documentation ports is as + follows:</para> - <itemizedlist> - <listitem> - <para>The - <package>misc/freebsd-doc-en</package> package or port installs - all of the English documentation.</para> - </listitem> + <itemizedlist> + <listitem> + <para>The <package>misc/freebsd-doc-en</package> package or + port installs all of the English documentation.</para> + </listitem> - <listitem> - <para>The - <package>misc/freebsd-doc-all</package> meta-package or port - installs all documentation in all available - languages.</para> - </listitem> + <listitem> + <para>The <package>misc/freebsd-doc-all</package> + meta-package or port installs all documentation in all + available languages.</para> + </listitem> - <listitem> - <para>There is a package and port for each - translation, such as - <package>misc/freebsd-doc-hu</package> for the - Hungarian documentation.</para> - </listitem> - </itemizedlist> + <listitem> + <para>There is a package and port for each translation, such + as <package>misc/freebsd-doc-hu</package> for the + Hungarian documentation.</para> + </listitem> + </itemizedlist> - <para>When binary packages are used, the &os; documentation - will be installed in all available - formats for the given language. For example, the following command will install the - latest package of the Hungarian - documentation:</para> + <para>When binary packages are used, the &os; documentation will + be installed in all available formats for the given language. + For example, the following command will install the latest + package of the Hungarian documentation:</para> - <screen>&prompt.root; <userinput>pkg install hu-freebsd-doc</userinput></screen> + <screen>&prompt.root; <userinput>pkg install hu-freebsd-doc</userinput></screen> - <note> - <para>Packages use a format that differs from the - corresponding port's name: - <literal><replaceable>lang</replaceable>-freebsd-doc</literal>, - where <replaceable>lang</replaceable> is the short format - of the language code, such as <literal>hu</literal> for - Hungarian, or <literal>zh_cn</literal> for Simplified - Chinese.</para> - </note> + <note> + <para>Packages use a format that differs from the + corresponding port's name: + <literal><replaceable>lang</replaceable>-freebsd-doc</literal>, + where <replaceable>lang</replaceable> is the short format of + the language code, such as <literal>hu</literal> for + Hungarian, or <literal>zh_cn</literal> for Simplified + Chinese.</para> + </note> - <para>To specify the format of the documentation, build the - port instead of installing the package. For example, to build and install the English - documentation:</para> + <para>To specify the format of the documentation, build the port + instead of installing the package. For example, to build and + install the English documentation:</para> - <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput> + <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput> &prompt.root; <userinput>make install clean</userinput></screen> - <para>The port provides a configuration menu where the format - to build and install can be specified. By default, split - <acronym>HTML</acronym>, similar to the format used on <uri - xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>, - and <acronym>PDF</acronym> are - selected.</para> - - <para>Alternately, several <command>make</command> options can be specified - when building a documentation port, including:</para> - - <variablelist> - <varlistentry> - <term><varname>WITH_HTML</varname></term> - - <listitem> - <para>Builds the HTML format with a single HTML file - per document. The formatted documentation is saved - to a file called <filename>article.html</filename>, - or <filename>book.html</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>WITH_PDF</varname></term> - - <listitem> - <para>The formatted documentation is saved to a - file called <filename>article.pdf</filename> or - <filename>book.pdf</filename>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>DOCBASE</varname></term> - - <listitem> - <para>Specifies where to install the documentation. - It defaults to - <filename>/usr/local/share/doc/freebsd</filename>.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>This example uses variables to install the Hungarian - documentation as a <acronym>PDF</acronym> in the specified - directory:</para> + <para>The port provides a configuration menu where the format to + build and install can be specified. By default, split + <acronym>HTML</acronym>, similar to the format used on <uri + xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>, + and <acronym>PDF</acronym> are selected.</para> + + <para>Alternately, several <command>make</command> options can + be specified when building a documentation port, + including:</para> + + <variablelist> + <varlistentry> + <term><varname>WITH_HTML</varname></term> + + <listitem> + <para>Builds the HTML format with a single HTML file per + document. The formatted documentation is saved to a + file called <filename>article.html</filename>, or + <filename>book.html</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>WITH_PDF</varname></term> + + <listitem> + <para>The formatted documentation is saved to a file + called <filename>article.pdf</filename> or + <filename>book.pdf</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>DOCBASE</varname></term> + + <listitem> + <para>Specifies where to install the documentation. It + defaults to + <filename>/usr/local/share/doc/freebsd</filename>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>This example uses variables to install the Hungarian + documentation as a <acronym>PDF</acronym> in the specified + directory:</para> - <screen>&prompt.root; cd /usr/ports/misc/freebsd-doc-hu + <screen>&prompt.root; cd /usr/ports/misc/freebsd-doc-hu &prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</screen> - <para>Documentation packages or ports can be updated using the - instructions in <xref linkend="ports"/>. - For example, the following command updates the installed - Hungarian documentation using - <package>ports-mgmt/portmaster</package> - by using packages only:</para> + <para>Documentation packages or ports can be updated using the + instructions in <xref linkend="ports"/>. For example, the + following command updates the installed Hungarian + documentation using <package>ports-mgmt/portmaster</package> + by using packages only:</para> - <screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen> + <screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen> </sect2> </sect1> @@ -1605,139 +1602,132 @@ Script started, output file is /var/tmp/ &prompt.root; <userinput>exit</userinput> Script done, …</screen> - <para><emphasis>Do not</emphasis> save the output in - <filename>/tmp</filename> as this directory may be cleared - at next reboot. A better place to save the file is - <filename>/var/tmp</filename> or in - <systemitem class="username">root</systemitem>'s home - directory.</para> + <para><emphasis>Do not</emphasis> save the output in + <filename>/tmp</filename> as this directory may be cleared at + next reboot. A better place to save the file is + <filename>/var/tmp</filename> or in <systemitem + class="username">root</systemitem>'s home directory.</para> - <para>While in <filename>/usr/src</filename> - type:</para> + <para>While in <filename>/usr/src</filename> type:</para> - <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> + <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> - <indexterm> - <primary><command>make</command></primary> - </indexterm> + <indexterm> + <primary><command>make</command></primary> + </indexterm> - <para>To rebuild the world, use &man.make.1;. This command - reads instructions from the <filename>Makefile</filename>, - which describes how the programs that comprise &os; should - be built and the order in which they should be built.</para> - - <para>The general format of the command is as follows:</para> - - <screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen> - - <para>In this example, - <option>-<replaceable>x</replaceable></option> is an option - passed to &man.make.1;. Refer to &man.make.1; for an - examples of available options.</para> - - <para><option>-D<replaceable>VARIABLE</replaceable></option> - passes a variable to the <filename>Makefile</filename>. The - behavior of the <filename>Makefile</filename> is controlled - by these variables. These are the same variables as are set - in <filename>/etc/make.conf</filename>, and this provides - another way of setting them. For example:</para> - - <screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen> - - <para>is another way of specifying that profiled libraries - should not be built, and corresponds with the</para> - - <programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting> - - <para>line in <filename>/etc/make.conf</filename>.</para> - - <para><replaceable>target</replaceable> tells &man.make.1; - what to do. Each <filename>Makefile</filename> defines a - number of different <quote>targets</quote>, and the choice - of target determines what happens.</para> - - <para>Some targets listed in the - <filename>Makefile</filename> are used by the build process - to break out the steps necessary to rebuild the system into - a number of sub-steps.</para> - - <para>Most of the time, no parameters need to be passed to - &man.make.1; and the command looks like this:</para> - - <screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen> - - <para>Where <replaceable>target</replaceable> is one of many - build options. The first target should always be - <buildtarget>buildworld</buildtarget>.</para> - - <para>As the names imply, - <buildtarget>buildworld</buildtarget> builds a complete new - tree under <filename>/usr/obj</filename> and - <buildtarget>installworld</buildtarget> installs this tree - on the current machine.</para> - - <para>Having separate options is useful for two reasons. - First, it allows for a <quote>self hosted</quote> build that - does not affect any components of a running system. Because - of this, <buildtarget>buildworld</buildtarget> can be run on - a machine running in multi-user mode with no fear of - ill-effects. It is still recommended that - <buildtarget>installworld</buildtarget> be run in part in - single user mode, though.</para> - - <para>Secondly, it allows NFS mounts to be used to upgrade - multiple machines on a network. If order to upgrade three - machines, <systemitem>A</systemitem>, - <systemitem>B</systemitem> and <systemitem>C</systemitem>, - run <command>make buildworld</command> and - <command>make installworld</command> on - <systemitem>A</systemitem>. <systemitem>B</systemitem> and - <systemitem>C</systemitem> should then NFS mount - <filename>/usr/src</filename> and - <filename>/usr/obj</filename> from - <systemitem>A</systemitem>, and run - <command>make installworld</command> to install the results - of the build on <systemitem>B</systemitem> and - <systemitem>C</systemitem>.</para> - - <para>Although the <buildtarget>world</buildtarget> target - still exists, users are strongly encouraged not to use - it.</para> - - <para>Instead, run:</para> - - <screen>&prompt.root; <userinput>make buildworld</userinput></screen> - - <para>It is possible to specify <option>-j</option> which - will cause <command>make</command> to spawn several - simultaneous processes. This is most useful on multi-CPU - machines. However, since much of the compiling process is - I/O bound rather than CPU bound, it is also useful on single - CPU machines.</para> - - <para>On a typical single-CPU machine, run:</para> - - <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen> - - <para>&man.make.1; will then 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> - - <para>On a multi-CPU machine using an SMP configured kernel, - try values between 6 and 10 and see how they speed things - up.</para> + <para>To rebuild the world, use &man.make.1;. This command + reads instructions from the <filename>Makefile</filename>, + which describes how the programs that comprise &os; should be + built and the order in which they should be built.</para> + + <para>The general format of the command is as follows:</para> + + <screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen> + + <para>In this example, + <option>-<replaceable>x</replaceable></option> is an option + passed to &man.make.1;. Refer to &man.make.1; for an examples + of available options.</para> + + <para><option>-D<replaceable>VARIABLE</replaceable></option> + passes a variable to the <filename>Makefile</filename>. The + behavior of the <filename>Makefile</filename> is controlled by + these variables. These are the same variables as are set in + <filename>/etc/make.conf</filename>, and this provides + another way of setting them. For example:</para> + + <screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen> + + <para>is another way of specifying that profiled libraries + should not be built, and corresponds with the</para> + + <programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting> + + <para>line in <filename>/etc/make.conf</filename>.</para> + + <para><replaceable>target</replaceable> tells &man.make.1; what + to do. Each <filename>Makefile</filename> defines a number of + different <quote>targets</quote>, and the choice of target + determines what happens.</para> + + <para>Some targets listed in the <filename>Makefile</filename> + are used by the build process to break out the steps + necessary to rebuild the system into a number of + sub-steps.</para> + + <para>Most of the time, no parameters need to be passed to + &man.make.1; and the command looks like this:</para> + + <screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen> + + <para>Where <replaceable>target</replaceable> is one of many + build options. The first target should always be + <buildtarget>buildworld</buildtarget>.</para> + + <para>As the names imply, <buildtarget>buildworld</buildtarget> + builds a complete new tree under <filename>/usr/obj</filename> + and <buildtarget>installworld</buildtarget> installs this tree + on the current machine.</para> + + <para>Having separate options is useful for two reasons. First, + it allows for a <quote>self hosted</quote> build that does not + affect any components of a running system. Because of this, + <buildtarget>buildworld</buildtarget> can be run on a machine + running in multi-user mode with no fear of ill-effects. It is + still recommended that <buildtarget>installworld</buildtarget> + be run in part in single user mode, though.</para> + + <para>Secondly, it allows NFS mounts to be used to upgrade + multiple machines on a network. If order to upgrade three + machines, <systemitem>A</systemitem>, + <systemitem>B</systemitem> and <systemitem>C</systemitem>, run + <command>make buildworld</command> and <command>make + installworld</command> on <systemitem>A</systemitem>. + <systemitem>B</systemitem> and <systemitem>C</systemitem> + should then NFS mount <filename>/usr/src</filename> and + <filename>/usr/obj</filename> from <systemitem>A</systemitem>, + and run <command>make installworld</command> to install the + results of the build on <systemitem>B</systemitem> and + <systemitem>C</systemitem>.</para> + + <para>Although the <buildtarget>world</buildtarget> target still + exists, users are strongly encouraged not to use it.</para> + + <para>Instead, run:</para> + + <screen>&prompt.root; <userinput>make buildworld</userinput></screen> + + <para>It is possible to specify <option>-j</option> which will + cause <command>make</command> to spawn several simultaneous + processes. This is most useful on multi-CPU machines. + However, since much of the compiling process is I/O bound + rather than CPU bound, it is also useful on single CPU + machines.</para> + + <para>On a typical single-CPU machine, run:</para> + + <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen> + + <para>&man.make.1; will then 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> + + <para>On a multi-CPU machine using an SMP configured kernel, try + values between 6 and 10 and see how they speed things + up.</para> - <indexterm> - <primary>rebuilding <quote>world</quote></primary> - <secondary>timings</secondary> - </indexterm> + <indexterm> + <primary>rebuilding <quote>world</quote></primary> + <secondary>timings</secondary> + </indexterm> - <para>Many factors influence the build time, but fairly recent - machines may only take a one or two hours to build the - &os.stable; tree, with no tricks or shortcuts used during - the process. A &os.current; tree will take somewhat - longer.</para> + <para>Many factors influence the build time, but fairly recent + machines may only take a one or two hours to build the + &os.stable; tree, with no tricks or shortcuts used during the + process. A &os.current; tree will take somewhat + longer.</para> </sect2> <sect2 xml:id="new-kernel"> @@ -2334,14 +2324,14 @@ Building everything.. class="directory">/usr</filename> with <option>noatime</option>.</para> - <para>The file system holding - <filename class="directory">/usr/obj</filename> can be mounted or - remounted with <option>async</option> so that disk + <para>The file system holding <filename + class="directory">/usr/obj</filename> can be mounted + or remounted with <option>async</option> so that disk writes happen asynchronously. The write completes - immediately, and the data is written to the disk a - few seconds later. This allows writes to be - clustered together, and can provide a dramatic - performance boost.</para> + immediately, and the data is written to the disk a few + seconds later. This allows writes to be clustered + together, and can provide a dramatic performance + boost.</para> <warning> <para>Keep in mind that this option makes the file @@ -2351,21 +2341,20 @@ Building everything.. machine restarts.</para> <para>If <filename>/usr/obj</filename> is the only - directory on this file system, this is not a - problem. If you have other, valuable data on the - same file system, ensure that there are verified - backups before enabling this option.</para> + directory on this file system, this is not a problem. + If you have other, valuable data on the same file + system, ensure that there are verified backups before + enabling this option.</para> </warning> <para>Turn off profiling by setting <quote>NO_PROFILE=true</quote> in <filename>/etc/make.conf</filename>.</para> - <para>Pass - <option>-j<replaceable>n</replaceable></option> to - &man.make.1; to run multiple processes in parallel. - This usually helps on both single- and - multi-processor machines.</para> + <para>Pass <option>-j<replaceable>n</replaceable></option> + to &man.make.1; to run multiple processes in parallel. + This usually helps on both single- and multi-processor + machines.</para> </listitem> </varlistentry> @@ -2428,16 +2417,15 @@ Building everything.. <sect2 xml:id="small-lan-preliminaries"> <title>Preliminaries</title> - <para>First, identify a set of machines which will run the - same set of binaries, known as a <emphasis>build - set</emphasis>. Each machine can have a custom kernel, but - will run the same userland binaries. From that set, choose a - machine to be the <emphasis>build machine</emphasis> that the - world and kernel are built on. Ideally, this is a fast - machine that has sufficient spare CPU to run - <command>make buildworld</command> and - <command>make buildkernel</command>. Select a machine to be - the <emphasis>test machine</emphasis>, which will test + <para>First, identify a set of machines which will run the same + set of binaries, known as a <emphasis>build set</emphasis>. + Each machine can have a custom kernel, but will run the same + userland binaries. From that set, choose a machine to be the + <emphasis>build machine</emphasis> that the world and kernel + are built on. Ideally, this is a fast machine that has + sufficient spare CPU to run <command>make buildworld</command> + and <command>make buildkernel</command>. Select a machine to + be the <emphasis>test machine</emphasis>, 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 @@ -2445,13 +2433,12 @@ Building everything.. <para>All the machines in this build set need to mount <filename>/usr/obj</filename> and - <filename>/usr/src</filename> from the same - machine, and at the same point. Ideally, those directories - are on two different drives on the build machine, but they can - be NFS mounted on that machine as well. For multiple - build sets, <filename>/usr/src</filename> - should be on one build machine, and NFS mounted on the - rest.</para> + <filename>/usr/src</filename> from the same machine, and at + the same point. Ideally, those directories are on two + different drives on the build machine, but they can be NFS + mounted on that machine as well. For multiple build sets, + <filename>/usr/src</filename> should be on one build machine, + and NFS mounted on the rest.</para> <para>Finally, ensure that <filename>/etc/make.conf</filename> and <filename>/etc/src.conf</filename> on all the machines in @@ -2463,8 +2450,8 @@ Building everything.. <filename>/etc/make.conf</filename>, and the build machine should list them all in <varname>KERNCONF</varname>, listing its own kernel first. The build machine must have the kernel - configuration files for each machine in - <filename class="directory">/usr/src/sys/<replaceable>arch</replaceable>/conf</filename> + configuration files for each machine in <filename + class="directory">/usr/src/sys/<replaceable>arch</replaceable>/conf</filename> if it is going to build their kernels.</para> </sect2> @@ -2472,18 +2459,18 @@ Building everything.. <title>The Base System</title> <para>On the build machine, build the kernel and world as - described in <xref linkend="make-buildworld"/>, but do - not install anything. After the build has finished, go to the + described in <xref linkend="make-buildworld"/>, but do not + install anything. After the build has finished, go to the test machine, and install the built kernel. If this machine mounts <filename>/usr/src</filename> and - <filename>/usr/obj</filename> via NFS, - enable the network and mount these directories after rebooting - to single user mode. The easiest way to do this is to boot to - multi-user, then run <command>shutdown now</command> to go to - single user mode. Once there, install the new kernel and - world and run <command>mergemaster</command> as usual. When - done, reboot to return to normal multi-user operations for - this machine.</para> + <filename>/usr/obj</filename> via NFS, enable the network and + mount these directories after rebooting to single user mode. + The easiest way to do this is to boot to multi-user, then run + <command>shutdown now</command> to go to single user mode. + Once there, install the new kernel and world and run + <command>mergemaster</command> as usual. When done, reboot to + return to normal multi-user operations for this + machine.</para> <para>After verifying that everything on the test machine is working properly, use the same procedure to install the new
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404281739.s3SHdd8W053879>