svn commit: r44734 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Dru Lavigne
dru at FreeBSD.org
Thu May 1 18:50:45 UTC 2014
Author: dru
Date: Thu May 1 18:50:44 2014
New Revision: 44734
URL: http://svnweb.freebsd.org/changeset/doc/44734
Log:
Editorial review of Variables and Targets section.
Move note on scripting the process to above the process.
More commits to come.
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:12:22 2014 (r44733)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Thu May 1 18:50:44 2014 (r44734)
@@ -1396,6 +1396,25 @@ before running "/usr/sbin/freebsd-update
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>
+
+ <screen>&prompt.root; <userinput>script <replaceable>/var/tmp/mw.out</replaceable></userinput>
+Script started, output file is /var/tmp/mw.out</screen>
+ </note>
+
<procedure>
<title>Overview of Build World Process</title>
@@ -1568,6 +1587,10 @@ before running "/usr/sbin/freebsd-update
<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
<filename>/usr/share/examples/etc/make.conf</filename>. Any
@@ -1597,140 +1620,70 @@ before running "/usr/sbin/freebsd-update
</sect2>
<sect2 xml:id="make-buildworld">
- <title>Recompile the Base System</title>
-
- <para>It is a good idea to save the output from running
- &man.make.1; 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 &man.script.1; with a
- parameter that specifies the name of the file to save all
- output to. 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 /var/tmp/mw.out</userinput>
-Script started, output file is /var/tmp/mw.out
-&prompt.root; <userinput>make TARGET</userinput>
-<emphasis>… compile, compile, compile …</emphasis>
-&prompt.root; <userinput>exit</userinput>
-Script done, …</screen>
+ <title>Variables and Targets</title>
- <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>
-
- <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen>
-
- <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>
+ <para>The general format for using <command>make</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 examples
+ passed to <command>make</command>. Refer to &man.make.1; for examples
of the available options.</para>
- <para><option>-D<replaceable>VARIABLE</replaceable></option>
- passes a variable to the <filename>Makefile</filename>. 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
- 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>
+ 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>
<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>
+ <para>It corresponds with this setting in
+ <filename>/etc/make.conf</filename>:</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>
+ <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>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
+ it allows for a 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
+ <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 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>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. 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>
+ 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 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
+ <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>
- <para>On a multi-CPU machine using an SMP configured kernel, try
- values between 6 and 10 and see how they speed things
+ <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>
<indexterm>
@@ -1738,28 +1691,22 @@ Script done, …</screen>
<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>
-
<note>
- <para>If variables were specified to
+ <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 never be used with
+ <option>-j</option> must <emphasis>never</emphasis> be used with
<buildtarget>installworld</buildtarget>.</para>
- <para>For example, if you ran:</para>
+ <para>For example, if this command was used:</para>
<screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen>
- <para>install the results with:</para>
+ <para>Install the results with:</para>
<screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen>
- <para>otherwise, the command will try to install profiled
+ <para>Otherwise, the second command will try to install profiled
libraries that were not built during the
<command>make buildworld</command> phase.</para>
</note>
More information about the svn-doc-head
mailing list