os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

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.

Browse source
This commit is contained in:
Eitan Adler 2012-11-26 02:58:34 +00:00
parent 5eb6805169
commit 0f21e94e49
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=40159
3 changed files with 246 additions and 14 deletions
en_US.ISO8859-1/books/developers-handbook
kernelbuild
chapter.xml
policies
chapter.xml
tools
chapter.xml

80
en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml
View file

@ -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>

155
en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
View file

@ -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>

25
en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
View file

@ -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>