svn commit: r40117 - in head/en_US.ISO8859-1/books/developers-handbook: kernelbuild policies tools
Eitan Adler
eadler at FreeBSD.org
Wed Nov 21 13:57:14 UTC 2012
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>$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 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; 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—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>
More information about the svn-doc-head
mailing list