jimzah/freebsd-src
1
0
Fork 0
mirror of https://github.com/freebsd/freebsd-src.git synced 2024-12-04 12:28:58 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

handbook.sgml

Browse Source 
Rearranged a few sections, add memoryuse section.

current.sgml, ports.sgml, porting.sgml
  Added a <label>s for cross reference targes.

submitters.sgml
  Lots of editing, added cross references to other sections of
  the handbook.  Added a sample BSD-style copyright statement.

eresources.sgml
  Updated the mailing list section, thanks to Peter Dufault.

authors.sgml
  Added Peter Dufault, David Greenman and Joerg Wunsch.

memoryuse.sgml
  A new section about how/where in PC memory the FreeBSD kernel
  gets loaded and run.
This commit is contained in:
John Fieber 1995-05-18 03:05:22 +00:00
parent 1190b57788
commit 84143d2611
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=8587
8 changed files with 500 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
share/doc/handbook/authors.sgml
View File

@ -1,4 +1,4 @@
<!-- $Id: authors.sgml,v 1.1.1.1 1995/04/28 16:19:59 jfieber Exp $ -->
<!-- $Id: authors.sgml,v 1.2 1995/05/11 22:31:19 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!--
@ -7,12 +7,15 @@ entities when referencing people.
-->
<!ENTITY a.asami "Satoshi Asami <tt>&lt;asami@FreeBSD.org&gt;</tt>">
<!ENTITY a.davidg "David Greenman <tt>&lt;davidg@Root.COM&gt;</tt>">
<!ENTITY a.dufalt "Peter Dufault <tt>&lt;dufault@hda.com&gt;</tt>">
<!ENTITY a.gclarkii "Gary Clark II <tt>&lt;gclarkii@FreeBSD.org&gt;</tt>">
<!ENTITY a.gena "Gennady B. Sorokopud <tt>&lt;gena@NetVision.net.il&gt;</tt>">
<!ENTITY a.ghelmer "Guy Helmer <tt>&lt;ghelmer@alpha.dsu.edu&gt;</tt>">
<!ENTITY a.gpalmer "Gary Palmer <tt>&lt;gpalmer@FreeBSD.org&gt;</tt>">
<!ENTITY a.jfieber "John Fieber <tt>&lt;jfieber@FreeBSD.org&gt;</tt>">
<!ENTITY a.jkh "Jordan Hubbard <tt>&lt;jkh@FreeBSD.org&gt;</tt>">
<!ENTITY a.joerg "Joerg Wunsch <tt>&lt;joerg_wunsch@uriah.heep.sax.de&gt;</tt>">
<!ENTITY a.john "John Lind <tt>&lt;john@starfire.MN.ORG&gt;</tt>">
<!ENTITY a.mark "Mark Murray <tt>&lt;mark@grondar.za&gt;</tt>">
<!ENTITY a.martin "Martin Renters <tt>&lt;martin@innovus.com&gt;</tt>">

6
share/doc/handbook/current.sgml
View File

@ -1,8 +1,8 @@
<!-- $Id: m_current.sgml,v 1.1 1995/04/10 02:35:57 jfieber Exp $ -->
<!-- $Id: current.sgml,v 1.1.1.1 1995/04/28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Staying current with FreeBSD</heading>
<chapt><heading>Staying current with FreeBSD<label id="current:"></heading>
<p><em>Contributed by &a.jkh;.</em>
@ -10,7 +10,7 @@
THE FREEBSD CURRENT POLICY
Last updated: $Date: 1995/04/10 02:35:57 $
Last updated: $Date: 1995/04/28 16:19:59 $
This document attempts to explain the rationale behind FreeBSD-current,
what you should expect should you decide to run it, and states some

365
share/doc/handbook/eresources.sgml
View File

@ -1,118 +1,297 @@
<!-- $Id:$ -->
<!-- $Id: eresources.sgml,v 1.1.1.1 1995/04/28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt>
<heading>Additional resources on the Internet</heading>
<sect>
<heading>Mailing lists</heading>
<heading>Mailing lists<label id="eresources:mailing-lists"></heading>
<p>The FreeBSD Project runs a number of Internet mailing
lists dedicated to the discussion of FreeBSD and
related topics. Users with access to Internet mail are
encouraged to subscribe to the lists that interest them
and ask questions. The procedure is quite simple, just
send a mail message to:
<tscreen>
<tt>majordomo@freebsd.org</tt>
</tscreen>
with a message body of:
<tscreen>
<tt><bf>subscribe <it>listname</it></bf></tt>
</tscreen>
where <em>listname</em> is one of the lists described
below. You can subscribe to multiple lists with a
single message by having several <em>subscribe</em>
lines. For more detailed information, send a message
to:
<tscreen>
<tt>majordomo@freebsd.org</tt>
</tscreen>
with a message body of
<tscreen>
<tt><bf>help</bf></tt>
</tscreen>
<p><em>Contributed by &a.dufalt;.<newline>
5 May 1995.</em>
<sect1>
<heading>General discussion lists</heading>
<p><descrip>
<tag>freebsd-announce</tag> Important announcements
about FreeBSD are posted here.
Though many of the FreeBSD development members read USENET, we cannot
always guarantee that we'll get to your questions in a timely fashion
(or at all) if you post them only to one of the comp.os.386bsd.*
groups. By addressing your questions to the appropriate mailing list
you will reach both us and a concentrated FreeBSD audience, invariably
assuring a better (or at least faster) response.
<tag>freebsd-questions</tag> General discussion of
problems people experience in setting up and using
FreeBSD.
There are list charters at the bottom of this document. Please read
the list charter before joining a list. We must strive to
keep the signal to noise ratio of the lists high, especially in
the technical lists.
<tag>freebsd-hackers</tag> Technical discussions
about the design and implementation of FreeBSD.
<sect1><heading>List summary</heading>
<tag>freebsd-bugs</tag> Bug reports and discussions
of reported bugs are posted here, although the
discussions are usually moved over to the
<em>freebsd-hackers</em> mailing list if the become involved.
</descrip>
<p><bf>General lists:</bf> The following are general lists that
anyone is free to join:
<verb>
List Purpose
----------------------------------------------------------------------
freebsd-announce Important events / milestones
freebsd-bugs Bug reports
freebsd-chat Non technical items related to the community
freebsd-policy Policy issues and suggestions
freebsd-questions User questions
freebsd-current Discussions about the use of FreeBSD-current
</verb>
<sect1>
<heading>CVS lists</heading>
<bf>Technical lists:</bf> The following are the technical lists. You should
read the charter carefully before joining them, and you should keep
your e-mail within the scope of the guidelines.
<verb>
List Purpose
----------------------------------------------------------------------
freebsd-doc Documentation project
freebsd-fs Filesystems
freebsd-hackers General Technical discussions
freebsd-hardware General discussion of FreeBSD hardware
freebsd-platforms Porting to Non-Intel platforms
freebsd-ports Discussion of "ports"
freebsd-security Security issues
freebsd-scsi SCSI subsystem
</verb>
<bf>Limited lists:</bf> The following are limited lists that you will need
approval to join. Even though access to these lists is controled,
anyone is free to send suggestions and comments to them. It is a
good idea establish a presence in the technical lists before asking
to join one of these limited lists.
<verb>
List Purpose
----------------------------------------------------------------------
freebsd-admin Administrative issues
freebsd-arch Architecture and design discussions
freebsd-core FreeBSD core team
freebsd-install Installation development
</verb>
<bf>CVS lists:</bf> The following lists are for people seeing the log messages
for source changes in specific areas:
<verb>
List name Source area Area Description (source for)
----------------------------------------------------------------------
cvs-CVSROOT /usr/src/[A-Z]* Top level /usr/src file changes
cvs-all /usr/src All changes to the tree (superset)
cvs-bin /usr/src/bin System binaries
cvs-etc /usr/src/etc System files
cvs-games /usr/src/games Games
cvs-gnu /usr/src/gnu GPL'd utilities
cvs-include /usr/src/include Include files
cvs-kerberosIV /usr/src/kerberosIV Kerberos encryption code
cvs-lib /usr/src/lib System libraries
cvs-libexec /usr/src/libexec System binaries
cvs-ports /usr/ports Ported software
cvs-sbin /usr/src/sbin System binaries
cvs-share /usr/src/share System shared files
cvs-sys /usr/src/sys Kernel
cvs-usrbin /usr/src/usr.bin Use binaries
cvs-usrsbin /usr/src/usr.sbin System binaries
</verb>
<sect1><heading>How to subscribe</heading>
<p>All mailing lists live on `FreeBSD.ORG', so to post to a list you
simply mail to `&lt;listname&gt;@FreeBSD.ORG'. It will then be redistributed
to mailing list members throughout the world.
To subscribe to a list, send mail to:
<tscreen><verb>
majordomo@FreeBSD.ORG
</verb></tscreen>
And include the keyword
<tscreen><verb>
subscribe <listname> [<optional address>]
</verb></tscreen>
In the body of your message. For example, to subscribe yourself to
freebsd-announce, you'd do:
<tscreen><verb>
% mail majordomo@FreeBSD.ORG
subscribe freebsd-announce
^D
</verb></tscreen>
If you want to subscribe yourself under a different name, or submit a
subscription request for a local mailing list (note: this is more efficient
if you have several interested parties at one site, and highly appreciated by
us!), you would do something like:
<tscreen><verb>
% mail majordomo@FreeBSD.ORG
subscribe freebsd-announce local-announce@somesite.com
^D
</verb></tscreen>
Finally, it is also possible to unsubscribe yourself from a list, get a
list of other list members or see the list of mailing lists again by
sending other types of control messages to majordomo. For a complete
list of available commands, do this:
<tscreen><verb>
% mail majordomo@FreeBSD.ORG
help
^D
</verb></tscreen>
Finally, we again request that you keep the technical mailing lists on
a technical track. If you're only interested in the "high points",
then it's suggested that you join freebsd-announce, which will contain
only infrequent traffic.
<sect1><heading>List charters</heading>
<p>
<descrip>
<tag/FREEBSD-ADMIN/ <em>Administrative issues</em><newline>
<!-- XXX -->
<tag/FREEBSD-ANNOUNCE/ <em>Important events / milestones</em><newline>
This is the mailing list for people interested only in occasional
announcements of significant freebsd events. This includes
announcements about snapshots and other releases. It contains
announcements of new FreeBSD capabilities. It may contain calls
for volunteers etc. This is a low volume list.
<tag/FREEBSD-ARCH/ <em>Architecture and design discussions</em><newline>
This is the mailing list for people discussing FreeBSD architectural
issues. It is a closed list, and not for general subscription.
<tag/FREEBSD-BUGS/ <em>Bug reports</em><newline>
This is the mailing list for reporting bugs in FreeBSD
Whenever possible, bugs should be
submitted using "send-pr".
<tag/FREEBSD-CHAT/ <em>Non technical items related to the
community</em><newline>
This list contains the overflow from the other lists about
non-technical, social information. It includes discussion about
whether Jordan looks like a tune ferret or not, whether or not to
type in capitals, who is drinking too much coffee, where the best
beer is brewed, who is brewing beer in their basement, and so on.
Occasional announcements of important events (such as upcoming
parties, weddings, births, new jobs, etc) can be made to the
technical lists, but the follow ups should be directed to this
-chat list.
<tag/FREEBSD-CORE/ <em>FreeBSD core team</em><newline>
This is an internal mailing list for use by the core members.
<tag/FREEBSD-CURRENT/ <em>Discussions about the use of
FreeBSD-current</em><newline>
This is the mailing list for users of freebsd-current. It includes
warnings about new features coming out in -current that will affect the
users, and instructions on steps that must be taken to remain -current.
Anyone running "current" must subscribe to this list.
<tag/FREEBSD-DOC/ <em>Documentation project</em><newline>
This mailing list belongs to the FreeBSD Doc Project and is for
the discussion of documentation related issues and projects.
<tag/FREEBSD-FS/ <em>Filesystems</em><newline>
Discussions concerning FreeBSD filesystems.
<tag/FREEBSD-HACKERS/ <em>Technical discussions</em><newline>
This is a forum for technical discussions related to FreeBSD. This
is the primary technical mailing list. It
is for individuals actively working on FreeBSD, to bring up problems
or discuss alternative solutions. Individuals interested in
following the technical discussion are also welcome.
<tag/FREEBSD-HARDWARE/ <em>General discussion of FreeBSD
hardware</em><newline>
General discussion about the types of hardware that FreeBSD runs on,
various problems and suggestions concerning what to buy or avoid.
<tag/FREEBSD-INSTALL/ <em>Installation discussion</em><newline>
This is the mailing list for people discussing FreeBSD installation
development for the 2.0 release.
<tag/FREEBSD-PLATFORMS/ <em>Porting to Non-Intel
platforms</em><newline>
Cross-platform freebsd issues, general discussion and proposals for
non-Intel FreeBSD ports.
<tag/FREEBSD-POLICY/ <em>Policy issues and
suggestions</em><newline>
This is a forum for policy discussions related to FreeBSD. This
includes where FreeBSD is going, how to set up a consortium, whether
or not and how to make FreeBSD pay for itself, how to attract more
users, and so on. When a topic relates directly to FreeBSD but has
little or no technical content then it should be sent to this list.
<tag/FREEBSD-PORTS/ <em>Discussion of "ports"</em><newline>
Discussions concerning FreeBSD's "ports collection" (/usr/ports), proposed
ports, modifications to ports collection infrastructure and general
coordination efforts.
<tag/FREEBSD-QUESTIONS/ <em>User questions</em><newline>
This is the mailing list for questions about FreeBSD. You should not
send "how to" questions to the technical lists unless you consider the
question to be pretty technical.
<tag/FREEBSD-SCSI/ <em>SCSI subsystem</em><newline>
This is the mailing list for people working on the scsi subsystem
for FreeBSD.
<tag/FREEBSD-SECURITY/ <em>Security issues</em><newline>
FreeBSD computer security issues (DES, Kerberos, known security holes and
fixes, etc).
</descrip>
<sect>
<heading>Usenet newsgroups</heading>
<heading>Usenet newsgroups</heading>
<p>While no newsgroups dedicated to FreeBSD exist, there
are many in which FreeBSD is discussed or are otherwise
relevant to FreeBSD users.
<p>While no newsgroups dedicated to FreeBSD exist, there
are many in which FreeBSD is discussed or are otherwise
relevant to FreeBSD users.
<sect1>
<heading>BSD specific newsgroups</heading>
<sect1>
<heading>BSD specific newsgroups</heading>
<p><itemize>
<item> comp.unix.bsd.freebsd.announce
<item> comp.unix.bsd.freebsd.misc
</itemize>
<p><itemize>
<item> comp.unix.bsd.freebsd.announce
<item> comp.unix.bsd.freebsd.misc
</itemize>
<sect1>
<heading>Other Unix newsgroups of interest</heading>
<sect1>
<heading>Other Unix newsgroups of interest</heading>
<p><itemize>
<item> comp.unix
<item> comp.unix.questions
<item> comp.unix.admin
<item> comp.unix.programmer
<item> comp.unix.shell
<item> comp.unix.user-friendly
<item> comp.security.unix
<item> comp.sources.unix
<item> comp.unix.advocacy
<item> comp.unix.misc
<item> comp.os.386bsd.announce
<item> comp.os.386bsd.apps
<item> comp.os.386bsd.bugs
<item> comp.os.386bsd.development
<item> comp.os.386bsd.misc
<item> comp.os.386bsd.questions
<item> comp.bugs.4bsd
<item> comp.bugs.4bsd.ucb-fixes
<item> comp.unix.bsd
</itemize>
<p><itemize>
<item> comp.unix
<item> comp.unix.questions
<item> comp.unix.admin
<item> comp.unix.programmer
<item> comp.unix.shell
<item> comp.unix.user-friendly
<item> comp.security.unix
<item> comp.sources.unix
<item> comp.unix.advocacy
<item> comp.unix.misc
<item> comp.os.386bsd.announce
<item> comp.os.386bsd.apps
<item> comp.os.386bsd.bugs
<item> comp.os.386bsd.development
<item> comp.os.386bsd.misc
<item> comp.os.386bsd.questions
<item> comp.bugs.4bsd
<item> comp.bugs.4bsd.ucb-fixes
<item> comp.unix.bsd
</itemize>
<sect1>
<heading>X-Window system</heading>
<sect1>
<heading>X-Window system</heading>
<p><itemize>
<item> comp.windows.x.i386unix
<item> comp.windows.x
<item> comp.windows.x.apps
<item> comp.windows.x.announce
<item> comp.windows.x.intrinsics
<item> comp.windows.x.motif
<item> comp.windows.x.pex
<item> comp.emulators.ms-windows.wine
</itemize>
<p><itemize>
<item> comp.windows.x.i386unix
<item> comp.windows.x
<item> comp.windows.x.apps
<item> comp.windows.x.announce
<item> comp.windows.x.intrinsics
<item> comp.windows.x.motif
<item> comp.windows.x.pex
<item> comp.emulators.ms-windows.wine
</itemize>
<sect>
<heading>Word Wide Web servers</heading>
<heading>Word Wide Web servers</heading>
<p><itemize>
<item> <url url="http://www.freebsd.org/"></item>
</itemize>
<p><itemize>
<item> <url url="http://www.freebsd.org/"></item>
</itemize>
</sect>

12
share/doc/handbook/handbook.sgml
View File

@ -1,4 +1,4 @@
<!-- $Id: handbook.sgml,v 1.5 1995/05/11 02:03:33 jfieber Exp $ -->
<!-- $Id: handbook.sgml,v 1.6 1995/05/11 22:31:23 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN" [
@ -16,6 +16,7 @@
<!ENTITY glossary SYSTEM "glossary.sgml">
<!ENTITY history SYSTEM "history.sgml">
<!ENTITY kerberos SYSTEM "kerberos.sgml">
<!ENTITY memoryuse SYSTEM "memoryuse.sgml">
<!ENTITY nfs SYSTEM "nfs.sgml">
<!ENTITY nutshell SYSTEM "nutshell.sgml">
<!ENTITY porting SYSTEM "porting.sgml">
@ -54,7 +55,7 @@ OUTLINE:
<author>
<name>The FreeBSD Documentation Project</name>
</author>
<date>May 11, 1995</date>
<date>May 17, 1995</date>
<abstract>Welcome to FreeBSD! This handbook covers the
installation and day to day use of FreeBSD.
@ -183,13 +184,16 @@ OUTLINE:
<!-- ************************************************************ -->
<part><heading>Advanced topics</heading>
&booting;
&current;
&ctm;
&sup;
<chapt><heading>Kernel debugging</heading>
&troubleshooting;
&submitters;
&booting;
&memoryuse;
&troubleshooting;
<!-- ************************************************************ -->
<part><heading>Additional resources</heading>
&bibliography;

55
share/doc/handbook/memoryuse.sgml Normal file
View File

@ -0,0 +1,55 @@
<!-- $Id:$ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>PC memory utilization</heading>
<p><em>Contributed by &a.joerg;.<newline>
16 Apr 1995.</em>
<bf>Question:</bf> <em>By the way, I have seen no description
of how FreeBSD uses PC memory, ie
what 0-640K gets used for, does the kernel load there or higher,
is the kernel relocated, etc. Is there a paper on this?</em>
The boot sector will be loaded at 0:0x7c00, and relocates itself
immediately to 0x7c0:0. (This is nothing magic, just an adjustment
for the %cs selector, done by an ljmp.)
It then loads the first 15 sectors at 0x10000 (segment BOOTSEG in the
biosboot Makefile), and sets up the stack to work below 0x1fff0.
After this, it jumps to the entry of boot2 within that code. I.e., it
jumps over itself and the (dummy) partition table, and it's going to
adjust the %cs selector---we are still in 16-bit mode there.
boot2 asks for the boot file, and examines the a.out header. It masks
the file entry point (usually 0xf0100000) by 0x00ffffff, and loads the
file there. Hence the usual load point is 1 MB (0x00100000). During
load, the boot code toggles back and forth between real and protected
mode, to use the BIOS in real mode.
The boot code itself uses segment selectors 0x18 and 0x20 for %cs and
%ds/%es in protected mode, and 0x28 to jump back into real mode. The
kernel is finally started with %cs 0x08 and %ds/%es/%ss 0x10, which
refer to dummy descriptors covering the whole address space.
The kernel will be started at its load point. Since it's been linked
for another (high) address, it will have to execute PIC until the page
table and page directory stuff is setup properly, at which point
paging will be enabled and the kernel will finally run at the address
for which it was linked.
The kernel still skips over the first 0x500 bytes of code, in the
assumption this were valuable BIOS data space (back from old days
where it has been loaded low).
<em>Contributed by &a.davidg;.<newline>
16 Apr 1995.</em>
The physical pages immediately following the kernel BSS contain
proc0's page directory, page tables, and upages. Some time later
when the VM system is initialized, the physical memory between
0x1000-0x9ffff and the physical memory after the kernel
(text+data+bss+proc0 stuff+other misc) is made available in the
form of general VM pages and added to the global free page list.

4
share/doc/handbook/porting.sgml
View File

@ -1,7 +1,7 @@
<!-- $Id: m_porting.sgml,v 1.1 1995/04/10 02:36:06 jfieber Exp $ -->
<!-- $Id: porting.sgml,v 1.1.1.1 1995/04/28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>Porting applications</heading>
<sect><heading>Porting applications<label id="porting:"></heading>
<p><em>Contributed by &a.jkh;.</em>

4
share/doc/handbook/ports.sgml
View File

@ -1,7 +1,7 @@
<!-- $Id: m_ports.sgml,v 1.1 1995/04/10 02:36:12 jfieber Exp $ -->
<!-- $Id: ports.sgml,v 1.1.1.1 1995/04/28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<sect><heading>The Ports collection</heading>
<sect><heading>The Ports collection<label id="ports:"></heading>
<p><em>Contributed by &a.gpalmer; and &a.jkh;.</em>

252
share/doc/handbook/submitters.sgml
View File

@ -1,4 +1,4 @@
<!-- $Id: m_submitters.sgml,v 1.1 1995/04/10 02:36:20 jfieber Exp $ -->
<!-- $Id: submitters.sgml,v 1.1.1.1 1995/04/28 16:19:59 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Contributing to FreeBSD</heading>
@ -11,22 +11,22 @@ customizations or fixes to the system which they'd like to incorporate
back into the mainstream sources, thus saving the work of having to
re-integrate the changes for each subsequent FreeBSD release. Submitting
something to the FreeBSD project is also an excellent way of getting your
code seriously *tested*! Many people have developed an original concept
code seriously <em>tested</em>! Many people have developed an original concept
far beyond what they might have envisioned at the start just due to the
flood of feedback and ideas generated by the many thousands of users of
FreeBSD. Contributions are also what FreeBSD lives and grows from,
and so your contributions are very important to the continued survival
of this communal effort of ours - we're very glad to see you reading this
documentation! :-)
of this communal effort of ours---we're very glad to see you reading this
documentation!
Submissions to FreeBSD can generally be classified into four catagories:
<enum>
<item> Ideas, general suggestions, bug reports.
<item> Addition, deletion, renaming or patching of existing sources.
<item> Significant contribution of a large body of independant work.
<item> Porting of freely available software.
<item>Ideas, general suggestions, bug reports.
<item>Addition, deletion, renaming or patching of existing sources.
<item>Significant contribution of a large body of independant work.
<item>Porting of freely available software.
</enum>
A submission in *any* of these catagories is highly welcomed as they
A submission in <em>any</em> of these catagories is highly welcomed as they
are each, in their own way, quite significant to the project.
@ -34,26 +34,30 @@ are each, in their own way, quite significant to the project.
<p>An idea, suggestion or fix can be communicated in one of the following ways:
<itemize>
<item> An idea or suggestion of general technical interest should be
mailed to &lt;hackers@freebsd.org&gt;. Likewise, people with an interest
in such things (and a tolerance for a HIGH volume of mail!) may
subscribe by sendimg mail to &lt;majordomo@freebsd.org&gt;. See also the
file /usr/share/FAQ/mailing-list.FAQ.
<item>An idea or suggestion of general technical interest should be
mailed to <tt>&lt;hackers@freebsd.org&gt;</tt>.
Likewise, people with an interest
in such things (and a tolerance for a <em>high</em>
volume of mail!) may
subscribe to the hackers mailing list by sendimg mail to
<tt>&lt;majordomo@freebsd.org&gt;</tt>.
See <ref id="eresources:mailing-lists"
name="mailing lists">
for more information about this and other mailing lists.
<item> An actual bug report should be filed by using the send-pr(1)
command (``man send-pr'' for information). This will prompt
<item>An actual bug report should be filed by using the
<tt>send-pr(1)</tt> program. This will prompt
you for various fields to fill in. Simply go to the fields
surrounded by &lt;&gt;'s and fill in your own information in place of
surrounded by <tt>&lt;&gt;</tt>'s and fill in your own
information in place of
what's suggested there. You should receive confirmation of your
bug report and a tracking number (which you should also reference in
any subsequent correspondence).
bug report and a tracking number. Keep this tracking number and use
it in any subsequent correspondence.
If you do not receive confirmation in a timely fashion (3 days to
a week, depending on your email connection) or are, for some
reason, unable to use the send-pr command, then you may also
file a bug report (or follow-up to one) by sending mail to:
&lt;bugs@freebsd.org&gt;
reason, unable to use the <tt>send-pr(1)</tt> command,
then you may also file a bug report by sending mail to
<tt>&lt;bugs@freebsd.org&gt;</tt>.
</itemize>
<sect><heading>Changes to the existing code</heading>
@ -61,90 +65,104 @@ are each, in their own way, quite significant to the project.
<p>An addition or change to the existing source code is a somewhat trickier
affair and depends a lot on how far out of date you are with the current
state of the core FreeBSD development. There is a special on-going release
of FreeBSD known as "FreeBSD-current" and made available in a variety of
ways (see /usr/share/FAQ/current-policy.FAQ and /usr/share/FAQ/ctm.FAQ) for
the convenience of developers who wish to actively work on the system.
of FreeBSD known as ``FreeBSD-current'' and made available in a variety of
ways for the convenience of developers who wish to actively work on the
system. See <ref id="current:" name="Staying current with
FreeBSD"> for more information about getting and using FreeBSD-current.
Working from older sources unfortunately means that your changes may
sometimes be too obsolete to use, or too divergent to allow for easy
re-integration. This can be minimized somewhat by subscribing to the
&lt;announce@freebsd.org&gt; mailing list (among others) where periodic
<tt>&lt;announce@freebsd.org&gt;</tt> mailing list, among
others, where periodic
announcements concerning the current state of the system are made.
If you see a change being proposed for which you have a better solution,
then please, by all means come forward with your contribution and we
by all means come forward with your contribution and we
will do our very best to evaluate it fairly and perhaps integrate it if
it is indeed a better (or easier :) solution.
it is indeed a better solution.
Assuming that you can manage to secure fairly up-to-date sources to base
your changes on, the next step is to produce a set of diffs to send to the
FreeBSD maintainers for evaluation and possible adoption. This is done
with the diff(1) command, with the FreeBSD maintainers preferring to receive
diffs in `context diff' form. See the man page for diff for more details
on producing both context and recursive context diffs
(diff -c &lt;oldfile&gt &lt;newfile&gt; or diff -c -r &lt;olddir&gt; &lt;newdir&gt;).
with the <tt>diff(1)</tt> command, with the FreeBSD
maintainers preferring to receive
diffs in `context diff' form. For example:
<tscreen><verb>
diff -c &lt;oldfile&gt &lt;newfile&gt;
</verb></tscreen>
or
<tscreen><verb>
diff -c -r &lt;olddir&gt &lt;newdir&gt;
</verb></tscreen>
See the man page for <tt>diff(1)</tt> for more details
on producing both context and recursive context diffs.
Once you have a set of diffs that are capable of taking a copy of the
original code and bringing it to a state identical to the "new" sources
(you may test this with the patch(1) command - see patch man page), you
should bundle them up in an email message and send it, along with a brief
description of what the diffs are for, to &lt;hackers@freebsd.org&gt;. Someone
will very likely get back in touch with you in 24 hours or less, assuming
of course that your diffs are interesting! :-)
Once you have a set of diffs that are capable of taking a copy
of the original code and bringing it to a state identical to
the ``new'' sources (you may test this with the
<tt>patch(1)</tt> command), you should bundle them up in an
email message and send it, along with a brief description of
what the diffs are for, to
<tt>&lt;hackers@freebsd.org&gt;</tt>. Someone will very
likely get back in touch with you in 24 hours or less,
assuming of course that your diffs are interesting!
If your changes don't express themselves well as diffs alone (e.g. you've
perhaps added, deleted or renamed files as well) then you may be better off
bundling any new files, diffs and instructions for deleting/renaming any
others into a tar file and running the `uuencode' program on it before
sending the output of that to &lt;hackers@freebsd.org&gt;. See the man pages
on tar and uuencode for more info on bundling files through the mail this
way.
If your changes don't express themselves well as diffs alone
(e.g. you've perhaps added, deleted or renamed files as well)
then you may be better off bundling any new files, diffs and
instructions for deleting/renaming any others into a
<tt>tar</tt> file and running the <tt>uuencode(1)</tt> program
on it before sending the output of that to
<tt>&lt;hackers@freebsd.org&gt;</tt>. See the man pages on
<tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more info on
bundling files through the mail this way.
If your change is of a potentially sensitive nature, e.g. you're unsure
of copyright issues governing its further distribution, or you're simply
not ready to release it without a tighter review first, then you should
send it to &lt;core@freebsd.org&gt; rather than &lt;hackers@freebsd.org&gt;. The core
mailing list reaches a much smaller group of people who do much of the
day-to-day work on FreeBSD. Note that this group is also VERY BUSY and so
you should really only mail to them in cases where mailing to hackers
truly is impractical.
If your change is of a potentially sensitive nature, for
example you're unsure of copyright issues governing its
further distribution, or you're simply not ready to release it
without a tighter review first, then you should send it to
<tt>&lt;core@freebsd.org&gt;</tt> rather than
<tt>&lt;hackers@freebsd.org&gt;</tt>. The core mailing list
reaches a much smaller group of people who do much of the
day-to-day work on FreeBSD. Note that this group is also
<em>very busy</em> and so you should only mail to them
in cases where mailing to hackers truly is impractical.
<sect><heading>Contributions of new code</heading>
<p>In the case of a significant contribution of a large body work, or the
addition of an important new feature to FreeBSD, it becomes almost always
necessary to either send changes as uuencoded tar files (see above)
or upload them to our ftp site:
<p>In the case of a significant contribution of a large body
work, or the addition of an important new feature to FreeBSD,
it becomes almost always necessary to either send changes as
uuencoded tar files or upload them to our ftp site <url
url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming"> where
users may log in anonymously and upload their work or download
the work-in-progress files left by others.
<url url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming">
Users may log in anonymously and upload their work or download the
work-in-progress files left by others.
When working with large amounts of code, the touchy subject of copyrights
also invariably comes up. The view of the FreeBSD project towards
acceptable copyrights (for code included in FreeBSD) are:
When working with large amounts of code, the touchy subject of
copyrights also invariably comes up. Acceptable copyrights
for code included in FreeBSD are:
<enum>
<item> Contributions under the BSD copyright (see the file
/usr/share/examples/etc/bsd-style-copyright for a template)
is greatly preferred due to its "no strings attached"
<item>Contributions under the BSD copyright
are greatly preferred due to its ``no strings attached''
nature and general attractiveness to commercial enterprises
who might then be inclined to invest something of their own
into FreeBSD.
<item> Contributions under the GNU Public License, or "GPL". This is
not quite as popular a solution for us, due to (all religious
issues aside) the amount of extra effort demanded of anyone
<item>Contributions under the GNU Public License, or ``GPL''. This is
not quite as popular a solution for us, due to
the amount of extra effort demanded of anyone
using the code for commercial purposes. However, given the
sheer quantity of GPL'd code we currently require (compiler,
assembler, text formatter, etc), it would be silly to pretend
that we couldn't deal with the GPL at all and so we have become
more willing to accept code with either the BSD or the GPL
copyright. Code under the GPL also goes into a different part
of the tree, that being /sys/gnu or /usr/src/gnu.
of the tree, that being <tt>/sys/gnu</tt> or
<tt>/usr/src/gnu</tt>.
<item> Contributions coming under any other type of copyright must be
<item>Contributions coming under any other type of copyright must be
carefully reviewed before their inclusion into FreeBSD will even
be considered. Contributions for which particularly restrictive
commercial copyrights apply are generally rejected, though the
@ -152,30 +170,68 @@ are each, in their own way, quite significant to the project.
their own channels.
</enum>
To place such a copyright on your work, place the following
text at the very beginning of every source code file you wish
to protect, replacing the text between the `<tt>%%</tt>' with
the appropriate information.
<tscreen><verb>
Copyright (c) %%proper_years_here%%
%%your_name_here%%, %%your_state%% %%your_zip%%. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer as
the first lines of this file unmodified.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgment:
This product includes software developed by %%your_name_here%%.
4. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
$Id$
</verb></tscreen>
For your convenience, a copy of this text can be found in
<tt>/usr/share/examples/etc/bsd-style-copyright</tt>.
<sect><heading>Porting of software</heading>
<p>The porting of freely available software, while perhaps not as gratifying
as developing your own package from scratch, is still a vital part of
FreeBSD's growth and of great usefulness to those who wouldn't otherwise
know where to turn for it. All ported software is organized into a
hierarchy know as ``the ports collection''. This collection enables
a new user to get a complete overview of what's available in a short time,
and with a logical (we hope) framework. The ports collection also saves
considerable space by not actually containing the the majority of the
sources being ported. This can be confusing to the new user and the file
/usr/share/FAQ/ports.FAQ goes some way towards explaing how it all works.
<p>The porting of freely available software, while perhaps not as
gratifying as developing your own package from scratch, is still
a vital part of FreeBSD's growth and of great usefulness to those
who wouldn't otherwise know where to turn for it. All ported
software is organized into a hierarchy know as ``the ports
collection''. This collection enables a new user to get a
complete overview of what's available in a short time, and with a
logical framework. The ports collection also saves
considerable space by not actually containing the the majority of
the sources being ported. See <ref id="ports:" name="The ports
collection"> for more information on using the ports collection
and <ref id="porting:" name="Porting applications"> for
guidelines on creating new ports. You may also send mail to
<tt>&lt;ports@freebsd.org&gt;</tt>.
If you have the ports collection on your machine, the file
/usr/ports/GUIDELINES also helps to explain the process of creating
and contributing a port of your own. For more information on the ports
collection (that wasn't available in the FAQ), you may also send mail to
&lt;ports@freebsd.org&gt;.
Whichever way you decide to contribute, we hope you'll find it an enjoyable
process and also realize how valuable your contributions are to the project!
FreeBSD is one of those great projects where the more we all put in, the
more we all get back out of it again, and with enough steady contributions
it begins to aquire a momentum of its own. It is through such momentum
Whichever way you decide to contribute, we hope you'll find it an
enjoyable process and also realize how valuable your
contributions are to the project! FreeBSD is one of those great
projects where the more we all put in, the more we all get back
out of it again, and with enough steady contributions it begins
to aquire a momentum of its own. It is through such momentum
that mountains are moved!