svn commit: r40160 - in head/en_US.ISO8859-1/books/developers-handbook: policies tools
Eitan Adler
eadler at FreeBSD.org
Mon Nov 26 03:00:20 UTC 2012
Author: eadler
Date: Mon Nov 26 03:00:20 2012
New Revision: 40160
URL: http://svnweb.freebsd.org/changeset/doc/40160
Log:
Recommit portions of r40117 which are still valid. Remove a ton of obsolete comments from the "developer's handbook".
Approved by: bcr (original commit)
Modified:
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/policies/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Mon Nov 26 02:58:34 2012 (r40159)
+++ head/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml Mon Nov 26 03:00:20 2012 (r40160)
@@ -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 Mon Nov 26 02:58:34 2012 (r40159)
+++ head/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml Mon Nov 26 03:00:20 2012 (r40160)
@@ -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-all
mailing list