os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Recommit portions of r40117 which are still valid. Remove a ton of obsolete comments from the "developer's handbook".

Browse source 
Approved by:	bcr (original commit)
This commit is contained in:
Eitan Adler 2012-11-26 03:00:20 +00:00
parent 0f21e94e49
commit 44d90126ab
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=40160
2 changed files with 10 additions and 170 deletions
en_US.ISO8859-1/books/developers-handbook
policies
chapter.xml
tools
chapter.xml

155
en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml
View file

@ -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>&dollar;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&lt;version&gt;' \
src/contrib/groff FSF v&lt;version&gt;
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 &lt;wl@gnu.org&gt; or
Ted Harding &lt;ted.harding@nessie.mcc.ac.uk&gt; 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>

25
en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml
View file

@ -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;&nbsp;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&mdash;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>