Date: Mon, 26 Nov 2012 03:00:20 +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: r40160 - in head/en_US.ISO8859-1/books/developers-handbook: policies tools Message-ID: <201211260300.qAQ30KC6077764@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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 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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201211260300.qAQ30KC6077764>