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>$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"> <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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201211260258.qAQ2wZ37077377>