Date: Wed, 21 Nov 2012 13:57:13 +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: r40117 - in head/en_US.ISO8859-1/books/developers-handbook: kernelbuild policies tools Message-ID: <201211211357.qALDvDsP064264@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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 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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201211211357.qALDvDsP064264>