Skip site navigation (1)Skip section navigation (2)
Date:      Mon, 26 Nov 2012 02:58:35 +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: r40159 - in head/en_US.ISO8859-1/books/developers-handbook: kernelbuild policies tools
Message-ID:  <201211260258.qAQ2wZ37077377@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: eadler
Date: Mon Nov 26 02:58:34 2012
New Revision: 40159
URL: http://svnweb.freebsd.org/changeset/doc/40159

Log:
  Revert r40117 which removed the last mention of the "old" way to build the kernel. This needs some reworking to explain why one would want to do this.

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	Sun Nov 25 21:31:10 2012	(r40158)
+++ head/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml	Mon Nov 26 02:58:34 2012	(r40159)
@@ -10,8 +10,80 @@
 
   <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.  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>
+    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>
 </chapter>

Modified: head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml	Sun Nov 25 21:31:10 2012	(r40158)
+++ head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml	Mon Nov 26 02:58:34 2012	(r40159)
@@ -142,12 +142,161 @@
       key issue in the decisions.</para>
 
     <note>
-      <para>Because it makes it harder to import future versions
-	minor, trivial and/or
+      <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
 	cosmetic changes are <emphasis>strongly discouraged</emphasis> on
-	files that are still tracking the vendor branch.</para>
+	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>
     </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	Sun Nov 25 21:31:10 2012	(r40158)
+++ head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml	Mon Nov 26 02:58:34 2012	(r40159)
@@ -349,11 +349,9 @@
   <sect1 id="tools-compiling">
     <title>Compiling with <command>cc</command></title>
 
-    <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
+    <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
       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
@@ -379,7 +377,14 @@
       <step>
 	<para>Convert the source code into assembly
 	  language&mdash;this is very close to machine code, but still
-	  understandable by humans.  Allegedly.</para>
+	  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>
       </step>
 
       <step>
@@ -532,7 +537,13 @@
 	    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.</para>
+	    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>
 
 	  <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?201211260258.qAQ2wZ37077377>