diff --git a/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.sgml
index 3140878c92..94cc1f5291 100644
--- a/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.sgml
@@ -1,231 +1,231 @@
MurrayStokelyContributed by JeroenRuigrok van der WervenIntroductionDeveloping on FreeBSDSo here we are. System all installed and you are ready to
start programming. But where to start? What does FreeBSD
provide? What can it do for me, as a programmer?These are some questions which this chapter tries to answer.
Of course, programming has different levels of proficiency like
any other trade. For some it is a hobby, for others it is their
profession. The information in this chapter might be aimed
toward the beginning programmer; indeed, it could serve useful
for the programmer unfamiliar with the &os; platform.The BSD VisionTo produce the best &unix; like operating system package
possible, with due respect to the original software tools
ideology as well as usability, performance and
stability.Architectural GuidelinesOur ideology can be described by the following
guidelinesDo not add new functionality unless an
implementor cannot complete a real application without
it.It is as important to decide what a system is
not as to decide what it is. Do not serve all the world's
needs; rather, make the system extensible so that additional
needs can be met in an upwardly compatible
fashion.The only thing worse than generalizing from one
example is generalizing from no examples at
all. If a problem is not completely understood, it is
probably best to provide no solution at all.If you can get 90 percent of the desired effect
for 10 percent of the work, use the simpler
solution.Isolate complexity as much as
possible.Provide mechanism, rather than policy. In
particular, place user interface policy in the client's
hands.From Scheifler & Gettys: "X Window System"The Layout of
/usr/srcThe complete source code to FreeBSD is available from our
- public CVS repository. The source code is normally installed in
+ public repository. The source code is normally installed in
/usr/src which contains the
following subdirectories:DirectoryDescriptionbin/Source for files in
/bincddl/Utilities covered by the Common Development and
Distribution Licensecontrib/Source for files from contributed software.crypto/Cryptographical sourcesetc/Source for files in /etcgames/Source for files in /usr/gamesgnu/Utilities covered by the GNU Public Licenseinclude/Source for files in /usr/includekerberos5/Source for Kerberos version 5lib/Source for files in /usr/liblibexec/Source for files in /usr/libexecrelease/Files required to produce a FreeBSD releaserescue/Build system for the
/rescue utilitiessbin/Source for files in /sbinsecure/FreeSec sourcesshare/Source for files in /usr/sharesys/Kernel source filestools/Tools used for maintenance and testing of
FreeBSDusr.bin/Source for files in /usr/binusr.sbin/Source for files in /usr/sbin
diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
index 3c37d8d4dc..c474d3a233 100644
--- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
+++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.sgml
@@ -1,709 +1,709 @@
Poul-HenningKampContributed by GiorgosKeramidasSource Tree Guidelines and PoliciesThis chapter documents various guidelines and policies in force for
the FreeBSD source tree.MAINTAINER on Makefilesports maintainerIf a particular portion of the &os; src/
distribution is being maintained by a person or group of persons,
this is communicated through an entry in the
src/MAINTAINERS file. Maintainers of ports
within the Ports Collection express their maintainership to the
world by adding a MAINTAINER line to the
Makefile of the port in question:MAINTAINER= email-addressesFor other parts of the repository, or for sections not listed
as having a maintainer, or when you are unsure who the active
maintainer is, try looking at the recent commit history of the
relevant parts of the source tree. It is quite often the case
that a maintainer is not explicitly named, but the people who are
actively working in a part of the source tree for, say, the last
couple of years are interested in reviewing changes. Even if this
is not specifically mentioned in the documentation or the source
itself, asking for a review as a form of courtesy is a very
reasonable thing to do.The role of the maintainer is as follows:The maintainer owns and is responsible for that code. This means
that he or she is responsible for fixing bugs and answering problem reports
pertaining to that piece of the code, and in the case of contributed
software, for tracking new versions, as appropriate.Changes to directories which have a maintainer defined shall be sent
to the maintainer for review before being committed. Only if the
maintainer does not respond for an unacceptable period of time, to
several emails, will it be acceptable to commit changes without review
by the maintainer. However, it is suggested that you try to have the
changes reviewed by someone else if at all possible.It is of course not acceptable to add a person or group as
maintainer unless they agree to assume this duty. On the other hand it
does not have to be a committer and it can easily be a group of
people.Poul-HenningKampContributed by DavidO'BrienGavinAtkinsonContributed Softwarecontributed softwareSome parts of the FreeBSD distribution consist of software that is
actively being maintained outside the FreeBSD project. For historical
reasons, we call this contributed software. Some
examples are sendmail, gcc and patch.Over the last couple of years, various methods have been used in
dealing with this type of software and all have some number of
advantages and drawbacks. No clear winner has emerged.Since this is the case, after some debate one of these methods has
been selected as the official method and will be required
for future imports of software of this kind. Furthermore, it is
strongly suggested that existing contributed software converge on this
model over time, as it has significant advantages over the old method,
including the ability to easily obtain diffs relative to the
official versions of the source by everyone (even without
direct repository access). This will make it significantly easier to return changes
to the primary developers of the contributed software.Ultimately, however, it comes down to the people actually doing the
work. If using this model is particularly unsuited to the package being
dealt with, exceptions to these rules may be granted only with the
approval of the core team and with the general consensus of the other
developers. The ability to maintain the package in the future will be a
key issue in the decisions.Because of some unfortunate design limitations with the RCS file
format and the use of vendor branches, minor, trivial and/or
cosmetic changes are strongly discouraged on
files that are still tracking the vendor branch. Spelling
fixes are explicitly included here under the
cosmetic category and are to be avoided.
The repository bloat impact from a single character
change can be rather dramatic.Vendor Imports with CVSThe file utility, used to identify
the format of a file, will be used as example of how this model
works:src/contrib/file 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
python subdirectory and files with the lt
prefix were eliminated before the import, amongst others.src/lib/libmagic contains a bmake style
Makefile that uses the standard
bsd.lib.mk makefile rules to produce the library
and install the documentation.src/usr.bin/file contains a bmake style
Makefile which will produce and install the
file program and its associated man-pages using the
standard bsd.prog.mk rules.The important thing here is that the
src/contrib/file directory is created according to
the rules: it is supposed to contain the sources as distributed (on a
proper vendor-branch and without RCS 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 works out.Because of the previously mentioned design limitations with
vendor branches, it is required that official 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 committed, as this
destroys the vendor branch coherency and makes importing future versions
rather difficult as there will be conflicts.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 not be removed.If it seems easier, the bmakeMakefiles 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
src/tools directory along with the port itself so
that it is available to future maintainers.In the src/contrib/file level directory, a file
called FREEBSD-upgrade should be added and it
should state things like:Which files have been left out.Where the original distribution was obtained from and/or the
official master site.Where to send patches back to the original authors.Perhaps an overview of the FreeBSD-specific changes that have
been made.Example wording from
src/contrib/groff/FREEBSD-upgrade is
below:$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 2005Another 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 FREEBSD-Xlist 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:&prompt.user; tarFREEBSD-Xlistvendor-source.tgzAn example of a FREEBSD-Xlist file, from
src/contrib/tcsh, is here:*/BUGS
*/config/a*
*/config/bs2000
*/config/bsd
*/config/bsdreno
*/config/[c-z]*
*/tests
*/win32Please do not import FREEBSD-upgrade or
FREEBSD-Xlist with the contributed source.
Rather you should add these files after the initial
import.Dag-ErlingSmørgravContributed by Vendor Imports with SVNThis section describes the vendor import procedure with
Subversion in details.Preparing the TreeIf this is your first import after the switch to
SVN, you will have to flatten and clean
up the vendor tree, and bootstrap merge history in the main
tree. If not, you can safely omit this step.During the conversion from CVS to
SVN, vendor branches were imported with
the same layout as the main tree. For example, the
foo vendor sources ended up in
vendor/foo/dist/contrib/foo,
but it is pointless and rather inconvenient. What we really
want is to have the vendor source directly in
vendor/foo/dist,
like this:&prompt.user; cdvendor/foo/dist/contrib/foo
&prompt.user; svn move $(svn list) ../..
&prompt.user; cd../..
&prompt.user; svn removecontrib
&prompt.user; svn propdel svn:mergeinfo
&prompt.user; svn commitNote that, the propdel bit is
necessary because starting with 1.5, Subversion will
automatically add svn:mergeinfo to any
directory you copy or move. In this case, you will not need
this information, since you are not going to merge anything
from the tree you deleted.You may want to flatten the tags as well. The
procedure is exactly the same. If you do this, put off
the commit until the end.Check the dist tree and perform any
cleanup that is deemed to be necessary. You may want to
disable keyword expansion, as it makes no sense on
unmodified vendor code. In some cases, it can be even be
harmful.&prompt.user; svn propdel svn:keywords .
&prompt.user; svn commitBootstrapping of svn:mergeinfo on the
target directory (in the main tree) to the revision that
corresponds to the last change was made to the vendor tree
prior to importing new sources is also needed:&prompt.user; cdhead/contrib/foo
&prompt.user; svn mergesvn_base/vendor/foo/dist@12345678.
&prompt.user; svn commitwhere svn_base is the base
directory of your SVN repository, e.g.
svn+ssh://svn.FreeBSD.org/base.Importing New SourcesPrepare a full, clean tree of the vendor sources. With
SVN, we can keep a full distribution in
the vendor tree without bloating the main tree. Import
everything but merge only what is needed.Note that you will need to add any files that were added
since the last vendor import, and remove any that were
removed. To facilitate this, you should prepare sorted
lists of the contents of the vendor tree and of the sources
you are about to import:&prompt.user; cdvendor/foo/dist
&prompt.user; svn list | grep '/$' | sort > ../old
&prompt.user; cd../foo-9.9
&prompt.user; find. f | cut 3- | sort > ../newWith these two files, the following command will list
list removed files (files only in
old):&prompt.user; comm ../old../newWhile the command below will list added files (files
only in
new):&prompt.user; comm ../old../newLet's put this together:&prompt.user; cdvendor/foo/foo-9.9
&prompt.user; tar cf - . | tar xf - ../dist
&prompt.user; cd../dist
&prompt.user; comm../old../new | xargs svn remove
&prompt.user; comm../old../new | xargs svn addIf there are new directories in the new distribution,
the last command will fail. You will have to add the
directories, and run it again. Conversely, if any
directories were removed, you will have to remove them
manually.Check properties on any new files:All text files
should have svn:eol-style set to
native.
All binary files should have
svn:mime-type set to
application/octet-stream, unless
there is a more appropriate media type.Executable files should have
svn:executable set to
*.There should be no other properties on any file in
the tree.You are ready to commit, but you should first check
the output of svn stat and svn
diff to make sure everything is in order.Once you have committed the new vendor release, you
should tag it for future reference. The best and quickest
way is to do it directly in the repository:&prompt.user; svn copysvn_base/vendor/foo/distsvn_base/vendor/foo/9.9To get the new tag, you can update your working copy of
vendor/foo.If you choose to do the copy in the checkout instead,
do not forget to remove the generated
svn:mergeinfo as described
above.Merging to -HEADAfter you have prepared your import, it is time to
merge. Option tells
SVN not to handle merge conflicts yet,
because they will be taken care of manually:&prompt.user; cdhead/contrib/foo
&prompt.user; svn update
&prompt.user; svn mergesvn_base/vendor/foo/distResolve any conflicts, and make sure that any files that
were added or removed in the vendor tree have been properly
added or removed in the main tree. It is always a good idea
to check differences against the vendor branch:&prompt.user; svn diffsvn_base/vendor/foo/dist.The option tells
SVN not to check files that are in the
vendor tree but not in the main tree.With SVN, there is no concept of on
or off the vendor branch. If a file that previously had
local modifications no longer does, just remove any
left-over cruft, such as &os; version tags, so it no
longer shows up in diffs against the vendor tree.If any changes are required for the world to build with
the new sources, make them now — and test until you
are satisfied that everything build and runs
correctly.CommitNow, you are ready to commit. Make sure you get
everything in one go. Ideally, you would have done all
steps in a clean tree, in which case you can just commit
from the top of that tree. That is the best way to avoid
surprises. If you do it properly, the tree will move
atomically from a consistent state with the old code to a
consistent state with the new code.Encumbered FilesIt might occasionally be necessary to include an encumbered file in
the FreeBSD source tree. For example, if a device requires a small
piece of binary code to be loaded to it before the device will operate,
and we do not have the source to that code, then the binary file is said
to be encumbered. The following policies apply to including encumbered
files in the FreeBSD source tree.Any file which is interpreted or executed by the system CPU(s)
and not in source format is encumbered.Any file with a license more restrictive than BSD or GNU is
encumbered.A file which contains downloadable binary data for use by the
hardware is not encumbered, unless (1) or (2) apply to it. It must
be stored in an architecture neutral ASCII format (file2c or
uuencoding is recommended).Any encumbered file requires specific approval from the
Core Team before it is added to the
- CVS repository.
+ repository.
Encumbered files go in src/contrib or
src/sys/contrib.The entire module should be kept together. There is no point in
splitting it, unless there is code-sharing with non-encumbered
code.Object files are named
arch/filename.o.uu>.Kernel files:Should always be referenced in
conf/files.* (for build simplicity).Should always be in LINT, but the
Core Team decides per case if it
should be commented out or not. The
Core Team can, of course, change
their minds later on.The Release Engineer
decides whether or not it goes into the release.User-land files:core teamThe Core team decides if
the code should be part of make world.release engineeringThe Release Engineering
decides if it goes into the release.SatoshiAsamiContributed by PeterWemmDavidO'BrienShared LibrariesIf you are adding shared library support to a port or other piece of
software that does not have one, the version numbers should follow these
rules. Generally, the resulting numbers will have nothing to do with
the release version of the software.The three principles of shared library building are:Start from 1.0If there is a change that is backwards compatible, bump minor
number (note that ELF systems ignore the minor number)If there is an incompatible change, bump major numberFor instance, added functions and bugfixes result in the minor
version number being bumped, while deleted functions, changed function
call syntax, etc. will force the major version number to change.Stick to version numbers of the form major.minor
(x.y). Our a.out
dynamic linker does not handle version numbers of the form
x.y.z
well. Any version number after the y
(i.e. the third digit) is totally ignored when comparing shared lib
version numbers to decide which library to link with. Given two shared
libraries that differ only in the micro revision,
ld.so will link with the higher one. That is, if you link
with libfoo.so.3.3.3, the linker only records
3.3 in the headers, and will link with anything
starting with
libfoo.so.3.(anything >=
3).(highest
available).ld.so will always use the highest
minor revision. For instance, it will use
libc.so.2.2 in preference to
libc.so.2.0, even if the program was initially
linked with libc.so.2.0.In addition, our ELF dynamic linker does not handle minor version
numbers at all. However, one should still specify a major and minor
version number as our Makefiles do the right thing
based on the type of system.For non-port libraries, it is also our policy to change the shared
library version number only once between releases. In addition, it is
our policy to change the major shared library version number only once
between major OS releases (i.e. from 6.0 to 7.0). When you make a
change to a system library that requires the version number to be
bumped, check the Makefile's commit logs. It is the
responsibility of the committer to ensure that the first such change
since the release will result in the shared library version number in
the Makefile to be updated, and any subsequent
changes will not.