Date: Thu, 1 May 2014 18:50:45 +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: r44734 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201405011850.s41Iojk5091857@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201405011850.s41Iojk5091857>