svn commit: r40159 - in head/en_US.ISO8859-1/books/developers-handbook: kernelbuild policies tools
Eitan Adler
eadler at FreeBSD.org
Mon Nov 26 02:58:35 UTC 2012
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>$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 at gnu.org> or
+Ted Harding <ted.harding at nessie.mcc.ac.uk> for inclusion in the next
+vendor release.
+
+ru at 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; 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—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>
More information about the svn-doc-head
mailing list