From owner-svn-doc-head@FreeBSD.ORG Thu May 1 18:50:45 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 57F485D7; Thu, 1 May 2014 18:50:45 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 390971E63; Thu, 1 May 2014 18:50:45 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s41IojNW091858; Thu, 1 May 2014 18:50:45 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s41Iojk5091857; Thu, 1 May 2014 18:50:45 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201405011850.s41Iojk5091857@svn.freebsd.org> From: Dru Lavigne Date: Thu, 1 May 2014 18:50:45 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 01 May 2014 18:50:45 -0000 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. + + It is a good idea to save the output from running + make to a file. If something goes wrong, a copy of + the error message can be posted to one of the &os; mailing + lists. + + The easiest way to do this is to use script with a + parameter that specifies the name of the file to save all + output to. Do not save the output to + /tmp as this directory may be cleared at + next reboot. A better place to save the file is + /var/tmp. Run this command immediately before rebuilding + the world, and then type exit when the + process has finished: + + &prompt.root; script /var/tmp/mw.out +Script started, output file is /var/tmp/mw.out + + Overview of Build World Process @@ -1568,6 +1587,10 @@ before running "/usr/sbin/freebsd-update This build world process uses several configuration files. + The Makefile located in /usr/src + describes how the programs that comprise &os; should be + built and the order in which they should be built. + The options available to make are described in &man.make.conf.5; and some common examples are included in /usr/share/examples/etc/make.conf. Any @@ -1597,140 +1620,70 @@ before running "/usr/sbin/freebsd-update - Recompile the Base System - - 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. - - 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 exit when the - process has finished: - - &prompt.root; script /var/tmp/mw.out -Script started, output file is /var/tmp/mw.out -&prompt.root; make TARGET -… compile, compile, compile … -&prompt.root; exit -Script done, … + Variables and Targets - Do not save the output in - /tmp as this directory may be cleared at - next reboot. A better place to save the file is - /var/tmp or in root's home directory. - - While in /usr/src type: - - &prompt.root; cd /usr/src - - - make - - - To rebuild the world, use &man.make.1;. This command - reads instructions from the Makefile, - which describes how the programs that comprise &os; should be - built and the order in which they should be built. - - The general format of the command is as follows: + The general format for using make is as + follows: &prompt.root; make -x -DVARIABLE target In this example, is an option - passed to &man.make.1;. Refer to &man.make.1; for examples + passed to make. Refer to &man.make.1; for examples of the available options. - - passes a variable to the Makefile. The + To pass a variable, specify the variable name with . + The behavior of the Makefile is controlled by - these variables. These are the same variables as are set in - /etc/make.conf, and this provides - another way of setting them. For example: + variables. These can either be set in + /etc/make.conf or they can be specified + when using make. For example, this + variable specifies that profiled libraries + should not be built: &prompt.root; make -DNO_PROFILE target - is another way of specifying that profiled libraries - should not be built, and corresponds with the + It corresponds with this setting in + /etc/make.conf: NO_PROFILE= true # Avoid compiling profiled libraries - line in /etc/make.conf. - - target tells &man.make.1; what - to do. Each Makefile defines a number of - different targets, and the choice of target - determines what happens. - - Some targets listed in the Makefile + The target tells make what + to do and the Makefile 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. - Most of the time, no parameters need to be passed to - &man.make.1; and the command looks like this: - - &prompt.root; make target - - Where target is one of many - build options. The first target should always be - buildworld. - - As the names imply, buildworld - builds a complete new tree under /usr/obj - and installworld installs this tree - on the current machine. - Having separate options is useful for two reasons. First, - it allows for a self hosted build that does not + it allows for a build that does not affect any components of a running system. Because of this, - buildworld can be run on a machine - running in multi-user mode with no fear of ill-effects. It is + buildworld can be safely run on a machine + running in multi-user mode. It is still recommended that installworld be run in part in single-user mode, though. - Secondly, it allows NFS mounts to be used to upgrade - multiple machines on a network. If order to upgrade three - machines, A, - B and C, run - make buildworld and make - installworld on A. - B and C - should then NFS mount /usr/src and - /usr/obj from A, - and run make installworld to install the - results of the build on B and - C. - - Although the world target still - exists, users are strongly encouraged not to use it. - - Instead, run: - - &prompt.root; make buildworld + Secondly, it allows NFS mounts to be used to upgrade + multiple machines on a network, as described in . It is possible to specify which will cause make 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. + processes. + Since much of the compiling process is I/O-bound + rather than CPU-bound, this is useful on both single CPU + and multi-CPU machines. - On a typical single-CPU machine, run: - - &prompt.root; make -j4 buildworld - - &man.make.1; will then have up to 4 processes running at + On a single-CPU 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. - On a multi-CPU machine using an SMP configured kernel, try - values between 6 and 10 and see how they speed things + &prompt.root; make -j4 buildworld + + On a multi-CPU machine, try + values between 6 and 10 to see how they speed things up. @@ -1738,28 +1691,22 @@ Script done, … timings - 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. - - If variables were specified to + If any variables were specified to make buildworld, specify the same variables to make installworld. However, - must never be used with + must never be used with installworld. - For example, if you ran: + For example, if this command was used: &prompt.root; make -DNO_PROFILE buildworld - install the results with: + Install the results with: &prompt.root; make -DNO_PROFILE installworld - otherwise, the command will try to install profiled + Otherwise, the second command will try to install profiled libraries that were not built during the make buildworld phase.