Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 21 Nov 2012 13:57:13 +0000 (UTC)
From:      Eitan Adler <eadler@FreeBSD.org>
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
Message-ID:  <201211211357.qALDvDsP064264@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
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 @@
 
   <para>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:</para>
-
-  <itemizedlist>
-    <listitem>
-      <para>The <quote>Traditional</quote> Way</para>
-    </listitem>
-
-    <listitem>
-      <para>The <quote>New</quote> Way</para>
-    </listitem>
-  </itemizedlist>
-
-  <note>
-    <para>It is supposed that the reader of this chapter is familiar
-      with the information described in the <ulink
-	url="../handbook/kernelconfig-building.html">Building and
-	Installing a Custom Kernel</ulink> 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.</para>
-  </note>
-
-  <sect1 id="kernelbuild-traditional">
-    <title>Building a Kernel the <quote>Traditional</quote> Way</title>
-
-    <para>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 <quote>buildkernel</quote> target of the toplevel
-      <filename class="directory">/usr/src/</filename> makefiles).
-      Building the kernel this way may be useful when working on the
-      kernel code and it may actually be faster than the
-      <quote>New</quote> 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;.</para>
-
-    <procedure>
-      <step>
-	<para>Run &man.config.8; to generate the kernel source
-	  code:</para>
-
-	<screen>&prompt.root; <userinput>/usr/sbin/config <replaceable>MYKERNEL</replaceable></userinput></screen>
-      </step>
-
-      <step>
-	<para>Change into the build directory.  &man.config.8; will
-	  print the name of this directory after being run as
-	  above.</para>
-
-	<screen>&prompt.root; <userinput>cd ../compile/<replaceable>MYKERNEL</replaceable></userinput></screen>
-      </step>
-
-      <step>
-	<para>Compile the kernel:</para>
-
-	<screen>&prompt.root; <userinput>make depend</userinput>
-&prompt.root; <userinput>make</userinput></screen>
-      </step>
-
-      <step>
-	<para>Install the new kernel:</para>
-
-	<screen>&prompt.root; <userinput>make install</userinput></screen>
-      </step>
-    </procedure>
-  </sect1>
-
-  <sect1 id="kernelbuild-new">
-    <title>Building a Kernel the <quote>New</quote> Way</title>
-
-    <para>This procedure is well supported and recommended under the
-      latest &os; releases and is documented in the <ulink
-	url="../handbook/kernelconfig-building.html">Building and
-	Installing a Custom Kernel</ulink> chapter of the &os;
-      Handbook.</para>
-  </sect1>
+    to build one.  This procedure is documented in the <ulink
+      url="../handbook/kernelconfig-building.html">Building and
+      Installing a Custom Kernel</ulink> chapter of the &os;
+    Handbook.</para>
 </chapter>

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.</para>
 
     <note>
-      <para>Because of some unfortunate design limitations with the <acronym role="Revision Control System">RCS</acronym> file
-	format and the use of vendor branches, minor, trivial and/or
+      <para>Because it makes it harder to import future versions
+	minor, trivial and/or
 	cosmetic changes are <emphasis>strongly discouraged</emphasis> on
-	files that are still tracking the vendor branch.  <quote>Spelling
-	fixes</quote> are explicitly included here under the
-	<quote>cosmetic</quote> category and are to be avoided.
-	The repository bloat impact from a single character
-	change can be rather dramatic.</para>
+	files that are still tracking the vendor branch.</para>
     </note>
 
-    <sect2 id="vendor-import-cvs">
-      <title>Vendor Imports with CVS</title>
-
-    <para>The <application>file</application> utility, used to identify
-      the format of a file, will be used as example of how this model
-      works:</para>
-
-    <para><filename>src/contrib/file</filename> 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
-      <filename>python</filename> subdirectory and files with the <filename>lt</filename>
-      prefix were eliminated before the import, amongst others.</para>
-
-    <para><filename>src/lib/libmagic</filename> contains a <application>bmake</application> style
-      <filename>Makefile</filename> that uses the standard
-      <filename>bsd.lib.mk</filename> makefile rules to produce the library
-      and install the documentation.</para>
-
-    <para><filename>src/usr.bin/file</filename> contains a <application>bmake</application> style
-      <filename>Makefile</filename> which will produce and install the
-      <command>file</command> program and its associated man-pages using the
-      standard <filename>bsd.prog.mk</filename> rules.</para>
-
-    <para>The important thing here is that the
-      <filename>src/contrib/file</filename> directory is created according to
-      the rules: it is supposed to contain the sources as distributed (on a
-      proper vendor-branch and without <acronym>RCS</acronym> 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 <quote>works out</quote>.</para>
-
-    <para>Because of the previously mentioned design limitations with
-      vendor branches, it is required that <quote>official</quote> 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 <quote>committed</quote>, as this
-      destroys the vendor branch coherency and makes importing future versions
-      rather difficult as there will be conflicts.</para>
-
-    <para>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 <emphasis>not</emphasis> be removed.</para>
-
-    <para>If it seems easier, the <command>bmake</command>
-      <filename>Makefile</filename>s 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
-      <filename>src/tools</filename> directory along with the port itself so
-      that it is available to future maintainers.</para>
-
-    <para>In the <filename>src/contrib/file</filename> level directory, a file
-      called <filename>FREEBSD-upgrade</filename> should be added and it
-      should state things like:</para>
-
-    <itemizedlist>
-      <listitem>
-	<para>Which files have been left out.</para>
-      </listitem>
-
-      <listitem>
-	<para>Where the original distribution was obtained from and/or the
-	  official master site.</para>
-      </listitem>
-
-      <listitem>
-	<para>Where to send patches back to the original authors.</para>
-      </listitem>
-
-      <listitem>
-	<para>Perhaps an overview of the FreeBSD-specific changes that have
-	  been made.</para>
-      </listitem>
-    </itemizedlist>
-
-    <para>Example wording from
-      <filename>src/contrib/groff/FREEBSD-upgrade</filename> is
-      below:</para>
-
-    <programlisting>&dollar;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&lt;version&gt;' \
-			src/contrib/groff FSF v&lt;version&gt;
-
-	   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 &lt;wl@gnu.org&gt; or
-Ted Harding &lt;ted.harding@nessie.mcc.ac.uk&gt; for inclusion in the next
-vendor release.
-
-ru@FreeBSD.org - 20 October 2005</programlisting>
-
-    <para>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 <filename>FREEBSD-Xlist</filename> 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:</para>
-
-    <screen>&prompt.user; <userinput><command>tar</command> <option>-X</option> <filename>FREEBSD-Xlist</filename> <option>-xzf</option> <filename><replaceable>vendor-source.tgz</replaceable></filename></userinput></screen>
-
-    <para>An example of a <filename>FREEBSD-Xlist</filename> file, from
-      <filename>src/contrib/tcsh</filename>, is here:</para>
-
-    <programlisting>*/BUGS
-*/config/a*
-*/config/bs2000
-*/config/bsd
-*/config/bsdreno
-*/config/[c-z]*
-*/tests
-*/win32</programlisting>
-
-    <note>
-      <para>Please do not import <filename>FREEBSD-upgrade</filename> or
-	<filename>FREEBSD-Xlist</filename> with the contributed source.
-	Rather you should add these files after the initial
-	import.</para>
-    </note>
-
-    </sect2>
-
     <sect2 id="vendor-import-svn">
       <sect2info>
 	<authorgroup>

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 @@
   <sect1 id="tools-compiling">
     <title>Compiling with <command>cc</command></title>
 
-    <para>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 <command>cc</command> or <command>gcc</command>.  The
+    <para>This section deals with the <application>gcc</application>
+      and <application>clang</application> compilers for C and C++,
+      since they come with the &os; base system.  Starting with
+      &os;&nbsp;10.X <command>clang</command> is installed as
+      <command>cc</command>.  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 @@
       <step>
 	<para>Convert the source code into assembly
 	  language&mdash;this is very close to machine code, but still
-	  understandable by humans.  Allegedly.
-
-	  <footnote>
-	    <para>To be strictly accurate, <command>cc</command> converts the
-	      source code into its own, machine-independent
-	      <firstterm>p-code</firstterm> instead of assembly language at
-	      this stage.</para>
-	  </footnote></para>
+	  understandable by humans.  Allegedly.</para>
       </step>
 
       <step>
@@ -537,13 +532,7 @@
 	    an executable that runs faster than normal.  You can add a
 	    number after the <option>-O</option> to specify a higher
 	    level of optimization, but this often exposes bugs in the
-	    compiler's optimizer.  For instance, the version of
-	    <command>cc</command> that comes with the 2.1.0 release of
-	    FreeBSD is known to produce bad code with the
-	    <option>-O2</option> option in some circumstances.</para>
-
-	  <para>Optimization is usually only turned on when compiling
-	    a release version.</para>
+	    compiler's optimizer.</para>
 
 	  <informalexample>
 	    <screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput>



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201211211357.qALDvDsP064264>