From owner-svn-doc-all@FreeBSD.ORG Mon Apr 28 17:39:39 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 6A801121; Mon, 28 Apr 2014 17:39:39 +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 5542A19CE; Mon, 28 Apr 2014 17:39:39 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3SHddhv053880; Mon, 28 Apr 2014 17:39:39 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3SHdd8W053879; Mon, 28 Apr 2014 17:39:39 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404281739.s3SHdd8W053879@svn.freebsd.org> From: Dru Lavigne Date: Mon, 28 Apr 2014 17:39:39 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 28 Apr 2014 17:39:39 -0000 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; cd /cdrom/X.Y-RELEASE/kernels &prompt.root; ./install.sh GENERIC - Replace X.Y-RELEASE + Replace X.Y-RELEASE with the actual version of the release being used. The GENERIC kernel will be installed in /boot/GENERIC by @@ -717,35 +718,35 @@ before running "/usr/sbin/freebsd-update 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 - (http://www.freebsd.org/doc/), + is always available on the &os; web site (http://www.freebsd.org/doc/), it can be handy to have an up-to-date, local copy of the &os; website, handbooks, FAQ, and articles. - + 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. - For information on editing and submitting corrections to - the documentation, refer to the &os; Documentation - Project Primer for New Contributors - (http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/). + For information on editing and submitting corrections to the + documentation, refer to the &os; Documentation Project Primer + for New Contributors (http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/). Updating Documentation from Source 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 svn, can be installed from the - textproc/docproj package or port - developed by the &os; Documentation Project. + textproc/docproj package or port developed + by the &os; Documentation Project. Once installed, use svn to fetch a clean copy of the documentation source. Replace https://svn0.us-west.FreeBSD.org - with the address of the closest geographic mirror from - : + with the address of the closest geographic mirror from : &prompt.root; svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc @@ -775,10 +776,9 @@ before running "/usr/sbin/freebsd-update &prompt.root; cd /usr/doc/en_US.ISO8859-1 &prompt.root; make install clean - An alternative way of - updating the documentation is to run this - command from /usr/doc or - the desired language-specific subdirectory: + An alternative way of updating the documentation is to run + this command from /usr/doc or the desired + language-specific subdirectory: &prompt.root; make update @@ -788,11 +788,12 @@ before running "/usr/sbin/freebsd-update &prompt.root; cd /usr/doc &prompt.root; make FORMATS='html html-split' install clean - 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 /etc/make.conf, or as - command-line options passed to make. + 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 /etc/make.conf, or + as command-line options passed to + make. The options include: @@ -814,8 +815,8 @@ before running "/usr/sbin/freebsd-update A single format or a list of output formats to be built. Currently, html, html-split, txt, - ps, and pdf - are supported. + ps, and pdf are + supported. @@ -859,138 +860,134 @@ before running "/usr/sbin/freebsd-update 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: + &os; documentation from sources. This section describes an + alternative method which uses the Ports Collection and makes + it possible to: - Install pre-built packages of the - documentation, without having to locally build anything - or install the documentation toolchain. + Install pre-built packages of the documentation, + without having to locally build anything or install the + documentation toolchain. - Build the documentation sources - through the ports framework, making the checkout and build - steps a bit easier. + Build the documentation sources through the ports + framework, making the checkout and build steps a bit + easier. 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 (http://www.freshports.org/docs/). - Organization of the documentation ports is as - follows: + Organization of the documentation ports is as + follows: - - - The - misc/freebsd-doc-en package or port installs - all of the English documentation. - + + + The misc/freebsd-doc-en package or + port installs all of the English documentation. + - - The - misc/freebsd-doc-all meta-package or port - installs all documentation in all available - languages. - + + The misc/freebsd-doc-all + meta-package or port installs all documentation in all + available languages. + - - There is a package and port for each - translation, such as - misc/freebsd-doc-hu for the - Hungarian documentation. - - + + There is a package and port for each translation, such + as misc/freebsd-doc-hu for the + Hungarian documentation. + + - 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: + 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: - &prompt.root; pkg install hu-freebsd-doc + &prompt.root; pkg install hu-freebsd-doc - - Packages use a format that differs from the - corresponding port's name: - lang-freebsd-doc, - where lang is the short format - of the language code, such as hu for - Hungarian, or zh_cn for Simplified - Chinese. - + + Packages use a format that differs from the + corresponding port's name: + lang-freebsd-doc, + where lang is the short format of + the language code, such as hu for + Hungarian, or zh_cn for Simplified + Chinese. + - To specify the format of the documentation, build the - port instead of installing the package. For example, to build and install the English - documentation: + To specify the format of the documentation, build the port + instead of installing the package. For example, to build and + install the English documentation: - &prompt.root; cd /usr/ports/misc/freebsd-doc-en + &prompt.root; cd /usr/ports/misc/freebsd-doc-en &prompt.root; make install clean - The port provides a configuration menu where the format - to build and install can be specified. By default, split - HTML, similar to the format used on http://www.FreeBSD.org, - and PDF are - selected. - - Alternately, several make options can be specified - when building a documentation port, including: - - - - WITH_HTML - - - Builds the HTML format with a single HTML file - per document. The formatted documentation is saved - to a file called article.html, - or book.html. - - - - - WITH_PDF - - - The formatted documentation is saved to a - file called article.pdf or - book.pdf. - - - - - DOCBASE - - - Specifies where to install the documentation. - It defaults to - /usr/local/share/doc/freebsd. - - - - - This example uses variables to install the Hungarian - documentation as a PDF in the specified - directory: + The port provides a configuration menu where the format to + build and install can be specified. By default, split + HTML, similar to the format used on http://www.FreeBSD.org, + and PDF are selected. + + Alternately, several make options can + be specified when building a documentation port, + including: + + + + WITH_HTML + + + Builds the HTML format with a single HTML file per + document. The formatted documentation is saved to a + file called article.html, or + book.html. + + + + + WITH_PDF + + + The formatted documentation is saved to a file + called article.pdf or + book.pdf. + + + + + DOCBASE + + + Specifies where to install the documentation. It + defaults to + /usr/local/share/doc/freebsd. + + + + + This example uses variables to install the Hungarian + documentation as a PDF in the specified + directory: - &prompt.root; cd /usr/ports/misc/freebsd-doc-hu + &prompt.root; cd /usr/ports/misc/freebsd-doc-hu &prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean - Documentation packages or ports can be updated using the - instructions in . - For example, the following command updates the installed - Hungarian documentation using - ports-mgmt/portmaster - by using packages only: + Documentation packages or ports can be updated using the + instructions in . For example, the + following command updates the installed Hungarian + documentation using ports-mgmt/portmaster + by using packages only: - &prompt.root; portmaster -PP hu-freebsd-doc + &prompt.root; portmaster -PP hu-freebsd-doc @@ -1605,139 +1602,132 @@ Script started, output file is /var/tmp/ &prompt.root; exit Script done, … - 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. + 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: + While in /usr/src type: - &prompt.root; cd /usr/src + &prompt.root; cd /usr/src - - make - + + 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: - - &prompt.root; make -x -DVARIABLE target - - In this example, - is an option - passed to &man.make.1;. Refer to &man.make.1; for an - examples of available options. - - - passes a variable to the Makefile. 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: - - &prompt.root; make -DNO_PROFILE target - - is another way of specifying that profiled libraries - should not be built, and corresponds with the - - 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 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 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 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 - - 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. - - On a typical single-CPU machine, run: - - &prompt.root; make -j4 buildworld - - &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. - - On a multi-CPU machine using an SMP configured kernel, - try values between 6 and 10 and see how they speed things - up. + 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: + + &prompt.root; make -x -DVARIABLE target + + In this example, + is an option + passed to &man.make.1;. Refer to &man.make.1; for an examples + of available options. + + + passes a variable to the Makefile. 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: + + &prompt.root; make -DNO_PROFILE target + + is another way of specifying that profiled libraries + should not be built, and corresponds with the + + 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 + 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 + 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 + 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 + + 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. + + On a typical single-CPU machine, run: + + &prompt.root; make -j4 buildworld + + &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. + + On a multi-CPU machine using an SMP configured kernel, try + values between 6 and 10 and see how they speed things + up. - - rebuilding world - timings - + + rebuilding world + 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. + 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. @@ -2334,14 +2324,14 @@ Building everything.. class="directory">/usr with . - The file system holding - /usr/obj can be mounted or - remounted with so that disk + The file system holding /usr/obj can be mounted + or remounted with 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. + 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. Keep in mind that this option makes the file @@ -2351,21 +2341,20 @@ Building everything.. machine restarts. If /usr/obj 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. + 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. Turn off profiling by setting NO_PROFILE=true in /etc/make.conf. - Pass - to - &man.make.1; to run multiple processes in parallel. - This usually helps on both single- and - multi-processor machines. + Pass + to &man.make.1; to run multiple processes in parallel. + This usually helps on both single- and multi-processor + machines. @@ -2428,16 +2417,15 @@ Building everything.. Preliminaries - First, identify a set of machines which will run the - same set of binaries, known as a build - set. Each machine can have a custom kernel, but - will run the same userland binaries. From that set, choose a - machine to be the build machine that the - world and kernel are built on. Ideally, this is a fast - machine that has sufficient spare CPU to run - make buildworld and - make buildkernel. Select a machine to be - the test machine, which will test + First, identify a set of machines which will run the same + set of binaries, known as a build set. + Each machine can have a custom kernel, but will run the same + userland binaries. From that set, choose a machine to be the + build machine that the world and kernel + are built on. Ideally, this is a fast machine that has + sufficient spare CPU to run make buildworld + and make buildkernel. Select a machine to + be the test machine, which will test software updates before they are put into production. This must 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.. All the machines in this build set need to mount /usr/obj and - /usr/src 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, /usr/src - should be on one build machine, and NFS mounted on the - rest. + /usr/src 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, + /usr/src should be on one build machine, + and NFS mounted on the rest. Finally, ensure that /etc/make.conf and /etc/src.conf on all the machines in @@ -2463,8 +2450,8 @@ Building everything.. /etc/make.conf, and the build machine should list them all in KERNCONF, listing its own kernel first. The build machine must have the kernel - configuration files for each machine in - /usr/src/sys/arch/conf + configuration files for each machine in /usr/src/sys/arch/conf if it is going to build their kernels. @@ -2472,18 +2459,18 @@ Building everything.. The Base System On the build machine, build the kernel and world as - described in , but do - not install anything. After the build has finished, go to the + described in , but do not + install anything. After the build has finished, go to the test machine, and install the built kernel. If this machine mounts /usr/src and - /usr/obj 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 shutdown now to go to - single user mode. Once there, install the new kernel and - world and run mergemaster as usual. When - done, reboot to return to normal multi-user operations for - this machine. + /usr/obj 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 + shutdown now to go to single user mode. + Once there, install the new kernel and world and run + mergemaster as usual. When done, reboot to + return to normal multi-user operations for this + machine. After verifying that everything on the test machine is working properly, use the same procedure to install the new