Editorial review of Variables and Targets section.
Move note on scripting the process to above the process. More commits to come. Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne
parent
73eb8113ed
commit
3246b81bed
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=44734
1 changed files with 60 additions and 113 deletions
|
|
@ -1396,6 +1396,25 @@ before running "/usr/sbin/freebsd-update install"</screen>
|
|||
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 install"</screen>
|
|||
<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 install"</screen>
|
|||
</sect2>
|
||||
|
||||
<sect2 xml:id="make-buildworld">
|
||||
<title>Recompile the Base System</title>
|
||||
<title>Variables and Targets</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>
|
||||
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue