Remove a ton of obsolete comments from the "developer's handbook".
Approved by: bcr (mentor)
This commit is contained in:
Eitan Adler
parent
d4f6e340b2
commit
50c1259b80
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=40117
3 changed files with 14 additions and 246 deletions
en_US.ISO8859-1/books/developers-handbook
|
|
@ -10,80 +10,8 @@
|
||||||
|
|
||||||
<para>Being a kernel developer requires understanding of the kernel
|
<para>Being a kernel developer requires understanding of the kernel
|
||||||
build process. To debug the &os; kernel it is required to be able
|
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>
|
to build one. This procedure is documented in the <ulink
|
||||||
|
url="../handbook/kernelconfig-building.html">Building and
|
||||||
<itemizedlist>
|
Installing a Custom Kernel</ulink> chapter of the &os;
|
||||||
<listitem>
|
Handbook.</para>
|
||||||
<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>
|
</chapter>
|
||||||
|
|
|
||||||
|
|
@ -142,161 +142,12 @@
|
||||||
key issue in the decisions.</para>
|
key issue in the decisions.</para>
|
||||||
|
|
||||||
<note>
|
<note>
|
||||||
<para>Because of some unfortunate design limitations with the <acronym role="Revision Control System">RCS</acronym> file
|
<para>Because it makes it harder to import future versions
|
||||||
format and the use of vendor branches, minor, trivial and/or
|
minor, trivial and/or
|
||||||
cosmetic changes are <emphasis>strongly discouraged</emphasis> on
|
cosmetic changes are <emphasis>strongly discouraged</emphasis> on
|
||||||
files that are still tracking the vendor branch. <quote>Spelling
|
files that are still tracking the vendor branch.</para>
|
||||||
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>
|
</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@gnu.org> or
|
|
||||||
Ted Harding <ted.harding@nessie.mcc.ac.uk> 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">
|
<sect2 id="vendor-import-svn">
|
||||||
<sect2info>
|
<sect2info>
|
||||||
<authorgroup>
|
<authorgroup>
|
||||||
|
|
|
||||||
|
|
@ -349,9 +349,11 @@
|
||||||
<sect1 id="tools-compiling">
|
<sect1 id="tools-compiling">
|
||||||
<title>Compiling with <command>cc</command></title>
|
<title>Compiling with <command>cc</command></title>
|
||||||
|
|
||||||
<para>This section deals only with the GNU compiler for C and C++,
|
<para>This section deals with the <application>gcc</application>
|
||||||
since that comes with the base FreeBSD system. It can be
|
and <application>clang</application> compilers for C and C++,
|
||||||
invoked by either <command>cc</command> or <command>gcc</command>. The
|
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
|
details of producing a program with an interpreter vary
|
||||||
considerably between interpreters, and are usually well covered
|
considerably between interpreters, and are usually well covered
|
||||||
in the documentation and on-line help for the
|
in the documentation and on-line help for the
|
||||||
|
|
@ -377,14 +379,7 @@
|
||||||
<step>
|
<step>
|
||||||
<para>Convert the source code into assembly
|
<para>Convert the source code into assembly
|
||||||
language—this is very close to machine code, but still
|
language—this is very close to machine code, but still
|
||||||
understandable by humans. Allegedly.
|
understandable by humans. Allegedly.</para>
|
||||||
|
|
||||||
<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>
|
||||||
|
|
||||||
<step>
|
<step>
|
||||||
|
|
@ -537,13 +532,7 @@
|
||||||
an executable that runs faster than normal. You can add a
|
an executable that runs faster than normal. You can add a
|
||||||
number after the <option>-O</option> to specify a higher
|
number after the <option>-O</option> to specify a higher
|
||||||
level of optimization, but this often exposes bugs in the
|
level of optimization, but this often exposes bugs in the
|
||||||
compiler's optimizer. For instance, the version of
|
compiler's optimizer.</para>
|
||||||
<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>
|
<informalexample>
|
||||||
<screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput>
|
<screen>&prompt.user; <userinput>cc -O -o foobar foobar.c</userinput>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue