From owner-svn-doc-all@FreeBSD.ORG Wed Nov 21 13:57:14 2012 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 06056BA5; Wed, 21 Nov 2012 13:57:14 +0000 (UTC) (envelope-from eadler@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id DE8548FC14; Wed, 21 Nov 2012 13:57:13 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.5/8.14.5) with ESMTP id qALDvDQU064267; Wed, 21 Nov 2012 13:57:13 GMT (envelope-from eadler@svn.freebsd.org) Received: (from eadler@localhost) by svn.freebsd.org (8.14.5/8.14.5/Submit) id qALDvDsP064264; Wed, 21 Nov 2012 13:57:13 GMT (envelope-from eadler@svn.freebsd.org) Message-Id: <201211211357.qALDvDsP064264@svn.freebsd.org> From: Eitan Adler Date: Wed, 21 Nov 2012 13:57:13 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40117 - in head/en_US.ISO8859-1/books/developers-handbook: kernelbuild policies tools 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.14 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: Wed, 21 Nov 2012 13:57:14 -0000 Author: eadler Date: Wed Nov 21 13:57:13 2012 New Revision: 40117 URL: http://svnweb.freebsd.org/changeset/doc/40117 Log: Remove a ton of obsolete comments from the "developer's handbook". Approved by: bcr (mentor) Modified: head/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml Modified: head/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml Wed Nov 21 13:57:11 2012 (r40116) +++ head/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml Wed Nov 21 13:57:13 2012 (r40117) @@ -10,80 +10,8 @@ Being a kernel developer requires understanding of the kernel build process. To debug the &os; kernel it is required to be able - to build one. There are two known ways to do so: - - - - The Traditional Way - - - - The New Way - - - - - It is supposed that the reader of this chapter is familiar - with the information described in the Building and - Installing a Custom Kernel chapter of the &os; - Handbook. If this is not the case, please read through the above - mentioned chapter to understand how the build process - works. - - - - Building a Kernel the <quote>Traditional</quote> Way - - Up to version 4.X of &os; this was the recommended way to - build a new kernel. It can still be used on newer versions - (instead of the buildkernel target of the toplevel - /usr/src/ makefiles). - Building the kernel this way may be useful when working on the - kernel code and it may actually be faster than the - New procedure when only a single option or two were - tweaked in the kernel configuration file. On the other hand, it - might lead to unexpected kernel build breakage when used by - beginners on newer versions of &os;. - - - - Run &man.config.8; to generate the kernel source - code: - - &prompt.root; /usr/sbin/config MYKERNEL - - - - Change into the build directory. &man.config.8; will - print the name of this directory after being run as - above. - - &prompt.root; cd ../compile/MYKERNEL - - - - Compile the kernel: - - &prompt.root; make depend -&prompt.root; make - - - - Install the new kernel: - - &prompt.root; make install - - - - - - Building a Kernel the <quote>New</quote> Way - - This procedure is well supported and recommended under the - latest &os; releases and is documented in the Building and - Installing a Custom Kernel chapter of the &os; - Handbook. - + to build one. This procedure is documented in the Building and + Installing a Custom Kernel chapter of the &os; + Handbook. Modified: head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Wed Nov 21 13:57:11 2012 (r40116) +++ head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Wed Nov 21 13:57:13 2012 (r40117) @@ -142,161 +142,12 @@ key issue in the decisions. - Because of some unfortunate design limitations with the RCS file - format and the use of vendor branches, minor, trivial and/or + Because it makes it harder to import future versions + minor, trivial and/or cosmetic changes are strongly discouraged on - files that are still tracking the vendor branch. Spelling - fixes are explicitly included here under the - cosmetic category and are to be avoided. - The repository bloat impact from a single character - change can be rather dramatic. + files that are still tracking the vendor branch. - - Vendor Imports with CVS - - The file utility, used to identify - the format of a file, will be used as example of how this model - works: - - src/contrib/file contains the source as - distributed by the maintainers of this package. Parts that are entirely - not applicable for &os; can be removed. In the case of &man.file.1;, the - python subdirectory and files with the lt - prefix were eliminated before the import, amongst others. - - src/lib/libmagic contains a bmake style - Makefile that uses the standard - bsd.lib.mk makefile rules to produce the library - and install the documentation. - - src/usr.bin/file contains a bmake style - Makefile which will produce and install the - file program and its associated man-pages using the - standard bsd.prog.mk rules. - - The important thing here is that the - src/contrib/file directory is created according to - the rules: it is supposed to contain the sources as distributed (on a - proper vendor-branch and without RCS keyword expansion) with as few - FreeBSD-specific changes as possible. If there are any doubts on - how to go about it, it is imperative that you ask first and not blunder - ahead and hope it works out. - - Because of the previously mentioned design limitations with - vendor branches, it is required that official patches from - the vendor be applied to the original distributed sources and the result - re-imported onto the vendor branch again. Official patches should never - be patched into the FreeBSD checked out version and committed, as this - destroys the vendor branch coherency and makes importing future versions - rather difficult as there will be conflicts. - - Since many packages contain files that are meant for compatibility - with other architectures and environments than FreeBSD, it is - permissible to remove parts of the distribution tree that are of no - interest to FreeBSD in order to save space. Files containing copyright - notices and release-note kind of information applicable to the remaining - files shall not be removed. - - If it seems easier, the bmake - Makefiles can be produced from the dist tree - automatically by some utility, something which would hopefully make it - even easier to upgrade to a new version. If this is done, be sure to - check in such utilities (as necessary) in the - src/tools directory along with the port itself so - that it is available to future maintainers. - - In the src/contrib/file level directory, a file - called FREEBSD-upgrade should be added and it - should state things like: - - - - Which files have been left out. - - - - Where the original distribution was obtained from and/or the - official master site. - - - - Where to send patches back to the original authors. - - - - Perhaps an overview of the FreeBSD-specific changes that have - been made. - - - - Example wording from - src/contrib/groff/FREEBSD-upgrade is - below: - - $FreeBSD: src/contrib/groff/FREEBSD-upgrade,v 1.5.12.1 2005/11/15 22:06:18 ru Exp $ - -This directory contains virgin copies of the original distribution files -on a "vendor" branch. Do not, under any circumstances, attempt to upgrade -the files in this directory via patches and a cvs commit. - -To upgrade to a newer version of groff, when it is available: - 1. Unpack the new version into an empty directory. - [Do not make ANY changes to the files.] - - 2. Use the command: - cvs import -m 'Virgin import of FSF groff v<version>' \ - src/contrib/groff FSF v<version> - - For example, to do the import of version 1.19.2, I typed: - cvs import -m 'Virgin import of FSF groff v1.19.2' \ - src/contrib/groff FSF v1_19_2 - - 3. Follow the instructions printed out in step 2 to resolve any - conflicts between local FreeBSD changes and the newer version. - -Do not, under any circumstances, deviate from this procedure. - -To make local changes to groff, simply patch and commit to the main -branch (aka HEAD). Never make local changes on the FSF branch. - -All local changes should be submitted to Werner Lemberg <wl@gnu.org> or -Ted Harding <ted.harding@nessie.mcc.ac.uk> for inclusion in the next -vendor release. - -ru@FreeBSD.org - 20 October 2005 - - Another approach my also be taken for the list of files to be - excluded, which is especially useful when the list is large or - complicated or where imports happen frequently. By creating a - file FREEBSD-Xlist in the same directory the - vendor source is imported into, containing a list of filename - patterns to be excluded one per line, future imports can often - performed with: - - &prompt.user; tar FREEBSD-Xlist vendor-source.tgz - - An example of a FREEBSD-Xlist file, from - src/contrib/tcsh, is here: - - */BUGS -*/config/a* -*/config/bs2000 -*/config/bsd -*/config/bsdreno -*/config/[c-z]* -*/tests -*/win32 - - - Please do not import FREEBSD-upgrade or - FREEBSD-Xlist with the contributed source. - Rather you should add these files after the initial - import. - - - - Modified: head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml Wed Nov 21 13:57:11 2012 (r40116) +++ head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml Wed Nov 21 13:57:13 2012 (r40117) @@ -349,9 +349,11 @@ Compiling with <command>cc</command> - This section deals only with the GNU compiler for C and C++, - since that comes with the base FreeBSD system. It can be - invoked by either cc or gcc. The + This section deals with the gcc + and clang compilers for C and C++, + since they come with the &os; base system. Starting with + &os; 10.X clang is installed as + cc. The details of producing a program with an interpreter vary considerably between interpreters, and are usually well covered in the documentation and on-line help for the @@ -377,14 +379,7 @@ Convert the source code into assembly language—this is very close to machine code, but still - understandable by humans. Allegedly. - - - To be strictly accurate, cc converts the - source code into its own, machine-independent - p-code instead of assembly language at - this stage. - + understandable by humans. Allegedly. @@ -537,13 +532,7 @@ an executable that runs faster than normal. You can add a number after the to specify a higher level of optimization, but this often exposes bugs in the - compiler's optimizer. For instance, the version of - cc that comes with the 2.1.0 release of - FreeBSD is known to produce bad code with the - option in some circumstances. - - Optimization is usually only turned on when compiling - a release version. + compiler's optimizer. &prompt.user; cc -O -o foobar foobar.c