diff --git a/share/doc/handbook/authors.sgml b/share/doc/handbook/authors.sgml index dc27d08d7cba..ecaa83ea10cc 100644 --- a/share/doc/handbook/authors.sgml +++ b/share/doc/handbook/authors.sgml @@ -1,21 +1,24 @@ - + <asami@FreeBSD.org>"> +<davidg@Root.COM>"> +<dufault@hda.com>"> <gclarkii@FreeBSD.org>"> <gena@NetVision.net.il>"> <ghelmer@alpha.dsu.edu>"> <gpalmer@FreeBSD.org>"> <jfieber@FreeBSD.org>"> <jkh@FreeBSD.org>"> +<joerg_wunsch@uriah.heep.sax.de>"> <john@starfire.MN.ORG>"> <mark@grondar.za>"> <martin@innovus.com>"> <md@bsc.no>"> <phk@FreeBSD.org>"> <wilko@yedi.iaf.nl>"> diff --git a/share/doc/handbook/current.sgml b/share/doc/handbook/current.sgml index 1e3af098a337..e467ad1bf7e8 100644 --- a/share/doc/handbook/current.sgml +++ b/share/doc/handbook/current.sgml @@ -1,179 +1,179 @@ - + -Staying current with FreeBSD +Staying current with FreeBSD

Contributed by &a.jkh;. What is FreeBSD-current?

FreeBSD-current is, quite literally, nothing more than a daily snapshot of the working sources for FreeBSD. These include work in progress, experimental changes, and transitional mechanisms that may or may not be present in the next official release of the software. While many of us compile almost daily from FreeBSD-current sources, there are periods of time when the sources are literally uncompilable. These problems are generally resolved as expeditiously as possible, but whether or not FreeBSD-current sources bring disaster or greatly desired functionality can literally be a matter of which part of any given 24 hour period you grabbed them in! Under certain circumstances we will sometimes make binaries for parts of FreeBSD-current available, but only because we're interested in getting something tested, not because we're in the business of providing binary releases of current. If we don't offer, please don't ask! It takes far too much time to do this as a general task. Who needs FreeBSD-current?

FreeBSD-current is made generally available for 3 primary interest groups: Members of the FreeBSD group who are actively working on one part or another of the source tree and for whom keeping `current' is an absolute requirement. Members of the FreeBSD group who are active ALPHA or BETA testers and willing to spend time working through problems in order to ensure that FreeBSD-current remains as sane as possible. These are also people who wish to make topical suggestions on changes and the general direction of FreeBSD. Peripheral members of the FreeBSD (or some other) group who merely wish to keep an eye on things and use the current sources for reference purposes (e.g. for reading, not running). These people also make the occasional comment or contribute code. What is FreeBSD-current NOT?

A fast-track to getting pre-release bits because there's something you heard was pretty cool in there and you want to be the first on your block to have it. A quick way of getting bug fixes. In any way ``officially supported'' by us. We do our best to help people genuinely in one of the 3 ``legitimate'' FreeBSD-current catagories, but we simply do not have the time to help every person who jumps into FreeBSD-current with more enthusiasm than knowledge of how to deal with experimental system software. This is not because we're mean and nasty people who don't like helping people out (we wouldn't even be doing FreeBSD if we were), it's literally because we can't answer 400 messages a day and actually work on FreeBSD! I'm sure if given the choice between having us answer lots of questions or continue to improve FreeBSD, most of you would vote for us improving it. Using FreeBSD-current

Join the freebsd-hackers and freebsd-commit mailing lists. This is not just a good idea, it's essential. If you aren't on freebsd-hackers, you won't read the comments that people are making about the current state of the system and thus will end up stumbling over a lot of problems that others have already found and solved. Even more importantly, you will miss out on potentially critical information (e.g. ``Yo, Everybody! Before you rebuild /usr/src, you must rebuild the kernel or your system will crash horribly!"). The freebsd-commit list will allow you to see the commit log entry for each change as its made. This can also contain important information, and will let you know what parts of the system are being actively changed. To join these lists, send mail to `majordomo@FreeBSD.ORG' and say: subscribe freebsd-hackers subscribe freebsd-commit In the body of your message. Optionally, you can also say `help' and MajorDomo will send you full help on how to subscribe and unsubscribe to the various other mailing lists we support. Grab the sources from ftp.FreeBSD.ORG. You can do this in three ways: Using the CTM facility desribed below. Unless you have a good TCP/IP connection at a flat rate, this is the way to do it. Use the CMU `sup' program (Software Update Protocol), also described below. This is the second most recommended method, since it allows you to grab the entire collection once and then only what's changed from then on. Many people run sup from cron and keep their sources up-to-date automatically. The problem is that sup does not use the bandwidth efficient, unless the round-trip is very fast. If the cost of connection or the duration of the session is a concern, use CTM. Use ftp. The source tree for FreeBSD-current is always "exported" on: ftp.FreeBSD.ORG:~ftp/pub/FreeBSD/FreeBSD-current We use `wu-ftpd' which allows compressed/tar'd grabbing of whole trees. e.g. you see: usr.bin/lex You can do: ftp> cd usr.bin ftp> get lex.tar.Z And it will get the whole directory for you as a compressed tar file. If you're grabbing the sources to run, and not just look at, then grab all of current, not just selected portions. The reason for this is that various parts of the source depend on updates elsewhere and trying to compile just a subset is almost guaranteed to get you into trouble. Before compiling current, read the Makefile in /usr/src carefully. You'll see one-time targets like `bootstrapld' which must be run as part of the upgrading process. Reading freebsd-hackers will keep you up-to-date on other bootstrapping procedures that sometimes become necessary as we move towards the next release. Be active! If you're running FreeBSD-current, we want to know what you have to say about it, especially if you have suggestions for enhancements or bug fixes. Suggestions with accompanying code are received most enthusiastically! diff --git a/share/doc/handbook/eresources.sgml b/share/doc/handbook/eresources.sgml index c4e85743fb0a..2105f3683998 100644 --- a/share/doc/handbook/eresources.sgml +++ b/share/doc/handbook/eresources.sgml @@ -1,118 +1,297 @@ - + Additional resources on the Internet - Mailing lists - -

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: - - majordomo@freebsd.org - - with a message body of: - - subscribe listname - - where listname is one of the lists described - below. You can subscribe to multiple lists with a - single message by having several subscribe - lines. For more detailed information, send a message - to: - - majordomo@freebsd.org - - with a message body of - - help - - - - General discussion lists -

- freebsd-announce Important announcements - about FreeBSD are posted here. - - freebsd-questions General discussion of - problems people experience in setting up and using - FreeBSD. - - freebsd-hackers Technical discussions - about the design and implementation of FreeBSD. - - freebsd-bugs Bug reports and discussions - of reported bugs are posted here, although the - discussions are usually moved over to the - freebsd-hackers mailing list if the become involved. - - - - CVS lists + Mailing lists + +

Contributed by &a.dufalt;. + 5 May 1995. + +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. + +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. + +List summary + +

General lists: The following are general lists that +anyone is free to join: + +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 + + +Technical lists: 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. + +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 + + +Limited lists: 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. + +List Purpose +---------------------------------------------------------------------- +freebsd-admin Administrative issues +freebsd-arch Architecture and design discussions +freebsd-core FreeBSD core team +freebsd-install Installation development + + +CVS lists: The following lists are for people seeing the log messages +for source changes in specific areas: + +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 + + +How to subscribe + +

All mailing lists live on `FreeBSD.ORG', so to post to a list you +simply mail to `<listname>@FreeBSD.ORG'. It will then be redistributed +to mailing list members throughout the world. + +To subscribe to a list, send mail to: + +majordomo@FreeBSD.ORG + +And include the keyword + +subscribe [] + +In the body of your message. For example, to subscribe yourself to +freebsd-announce, you'd do: + +% mail majordomo@FreeBSD.ORG +subscribe freebsd-announce +^D + +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: + +% mail majordomo@FreeBSD.ORG +subscribe freebsd-announce local-announce@somesite.com +^D + +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: + +% mail majordomo@FreeBSD.ORG +help +^D + +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. + +List charters + +

+ +Administrative issues + + +Important events / milestones +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. + +Architecture and design discussions +This is the mailing list for people discussing FreeBSD architectural +issues. It is a closed list, and not for general subscription. + +Bug reports +This is the mailing list for reporting bugs in FreeBSD +Whenever possible, bugs should be +submitted using "send-pr". + +Non technical items related to the + community +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. + +FreeBSD core team +This is an internal mailing list for use by the core members. + +Discussions about the use of + FreeBSD-current +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. + +Documentation project +This mailing list belongs to the FreeBSD Doc Project and is for +the discussion of documentation related issues and projects. + +Filesystems +Discussions concerning FreeBSD filesystems. + +Technical discussions +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. + +General discussion of FreeBSD + hardware +General discussion about the types of hardware that FreeBSD runs on, +various problems and suggestions concerning what to buy or avoid. + +Installation discussion +This is the mailing list for people discussing FreeBSD installation +development for the 2.0 release. + +Porting to Non-Intel + platforms +Cross-platform freebsd issues, general discussion and proposals for +non-Intel FreeBSD ports. + +Policy issues and + suggestions +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. + +Discussion of "ports" +Discussions concerning FreeBSD's "ports collection" (/usr/ports), proposed +ports, modifications to ports collection infrastructure and general +coordination efforts. + +User questions +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. + +SCSI subsystem +This is the mailing list for people working on the scsi subsystem +for FreeBSD. + +Security issues +FreeBSD computer security issues (DES, Kerberos, known security holes and +fixes, etc). + - Usenet newsgroups - -

While no newsgroups dedicated to FreeBSD exist, there - are many in which FreeBSD is discussed or are otherwise - relevant to FreeBSD users. - - - BSD specific newsgroups - -

- comp.unix.bsd.freebsd.announce - comp.unix.bsd.freebsd.misc - - - - Other Unix newsgroups of interest - -

- comp.unix - comp.unix.questions - comp.unix.admin - comp.unix.programmer - comp.unix.shell - comp.unix.user-friendly - comp.security.unix - comp.sources.unix - comp.unix.advocacy - comp.unix.misc - comp.os.386bsd.announce - comp.os.386bsd.apps - comp.os.386bsd.bugs - comp.os.386bsd.development - comp.os.386bsd.misc - comp.os.386bsd.questions - comp.bugs.4bsd - comp.bugs.4bsd.ucb-fixes - comp.unix.bsd - - - - X-Window system - -

- comp.windows.x.i386unix - comp.windows.x - comp.windows.x.apps - comp.windows.x.announce - comp.windows.x.intrinsics - comp.windows.x.motif - comp.windows.x.pex - comp.emulators.ms-windows.wine - + Usenet newsgroups + +

While no newsgroups dedicated to FreeBSD exist, there + are many in which FreeBSD is discussed or are otherwise + relevant to FreeBSD users. + + + BSD specific newsgroups + +

+ comp.unix.bsd.freebsd.announce + comp.unix.bsd.freebsd.misc + + + + Other Unix newsgroups of interest + +

+ comp.unix + comp.unix.questions + comp.unix.admin + comp.unix.programmer + comp.unix.shell + comp.unix.user-friendly + comp.security.unix + comp.sources.unix + comp.unix.advocacy + comp.unix.misc + comp.os.386bsd.announce + comp.os.386bsd.apps + comp.os.386bsd.bugs + comp.os.386bsd.development + comp.os.386bsd.misc + comp.os.386bsd.questions + comp.bugs.4bsd + comp.bugs.4bsd.ucb-fixes + comp.unix.bsd + + + + X-Window system + +

+ comp.windows.x.i386unix + comp.windows.x + comp.windows.x.apps + comp.windows.x.announce + comp.windows.x.intrinsics + comp.windows.x.motif + comp.windows.x.pex + comp.emulators.ms-windows.wine + - Word Wide Web servers + Word Wide Web servers -

- - +

+ + diff --git a/share/doc/handbook/handbook.sgml b/share/doc/handbook/handbook.sgml index 4e23dbfcef4b..dedf8b09bc9e 100644 --- a/share/doc/handbook/handbook.sgml +++ b/share/doc/handbook/handbook.sgml @@ -1,200 +1,204 @@ - + %authors; + ]> FreeBSD Handbook <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. This manual is a <bf>work in progress</bf> and is the work of many individials. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to &a.jfieber; or to the FreeBSD Documentantion Project mailing list <tt><doc@freebsd.org></tt>. </abstract> <toc> <!-- ************************************************************ --> <part><heading>Basics</heading> <chapt><heading>Introduction</heading> &nutshell; &history; <sect><heading>About this release</heading> <sect><heading>FreeBSD now and in the future</heading> <chapt><heading>Installing FreeBSD</heading> <sect><heading>Preparing for the installation</heading> <sect1><heading>Hardware checklist</heading> <sect2><heading>minimal requirements</heading> <sect2><heading>IRQs, IO Addresses, and DMA channels</heading> <sect1><heading>Software checklist</heading> <sect2><heading>Making the installation floppies</heading> <sect2><heading>CD-ROM</heading> <sect2><heading>Tape</heading> <sect2><heading>Disk</heading> <sect><heading>Installation</heading> <sect><heading>Set up a user account</heading> &basics; <chapt><heading>Installing applications</heading> <sect><heading>Installing packages</heading> &ports; &porting; <!-- ************************************************************ --> <part><heading>System Administration</heading> <chapt><heading>Reconfiguring the kernel</heading> <chapt><heading>Users, groups and security</heading> <sect><heading>DES, MD5 and Crypt</heading> &kerberos; <sect><heading>S/Key</heading> <sect><heading>Firewalls</heading> <chapt><heading>The X-Window System</heading> <chapt><heading>Printing</heading> <chapt><heading>Managing hardware</heading> &scsi; <sect><heading>adding/reconfiguring disks</heading> <sect><heading>tapes and backups</heading> <sect><heading>serial ports</heading> <sect><heading>sound cards</heading> <chapt><heading>PC Hardware compatibility</heading> <sect><heading>CORE/PROCESSING</heading> <sect1><heading>Motherboards</heading> <sect2><heading>ISA</heading> <sect2><heading>EISA</heading> <sect2><heading>VLB</heading> <sect2><heading>PCI</heading> <sect1><heading>CPUs/FPUs</heading> <sect1><heading>Memory</heading> <sect1><heading>BIOS</heading> <sect><heading>INPUT/OUTPUT</heading> <sect1><heading>Video cards</heading> <sect1><heading>Sound cards</heading> <sect1><heading>Serial ports (including multiport cards)</heading> <sect1><heading>Parallel ports</heading> <sect1><heading>Modems</heading> <sect1><heading>Etherenet cards</heading> <sect1><heading>Keyboards</heading> <sect1><heading>Mice</heading> <sect1><heading>Other (joysticks? tablets?)</heading> <sect><heading>STORAGE</heading> <sect1><heading>Disk/tape controllers</heading> <sect2><heading>SCSI</heading> <sect2><heading>IDE</heading> <sect2><heading>Floppy</heading> <sect1><heading>Hard drives</heading> <sect1><heading>Tape drives</heading> <sect1><heading>CD-ROM drives</heading> <sect1><heading>Other</heading> <sect><heading>OTHER</heading> <sect1><heading>PCMCIA</heading> <!-- ************************************************************ --> <part><heading>Network Communications</heading> <chapt><heading>Basic Networking</heading> <sect><heading>Ethernet basics</heading> <sect><heading>Serial basics</heading> <sect><heading>Hardwired Terminals</heading> &dialup; <chapt><heading>PPP and SLIP</heading> &ppp; &slipc; &slips; <chapt><heading>Advanced networking</heading> <sect><heading>Gateways and routing</heading> &nfs; <sect><heading>Yellow Pages/NIS</heading> &diskless; <sect><heading>ISDN</heading> <chapt><heading>Mail</heading> <!-- ************************************************************ --> <part><heading>Advanced topics</heading> - &booting; ¤t; &ctm; ⊃ <chapt><heading>Kernel debugging</heading> - &troubleshooting; &submitters; + &booting; + &memoryuse; + &troubleshooting; + +<!-- ************************************************************ --> <part><heading>Additional resources</heading> &bibliography; &eresources; &glossary; </book> </linuxdoc> diff --git a/share/doc/handbook/memoryuse.sgml b/share/doc/handbook/memoryuse.sgml new file mode 100644 index 000000000000..4c538bc54d8e --- /dev/null +++ b/share/doc/handbook/memoryuse.sgml @@ -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. + + diff --git a/share/doc/handbook/porting.sgml b/share/doc/handbook/porting.sgml index 0f972d051a72..c558e2e04438 100644 --- a/share/doc/handbook/porting.sgml +++ b/share/doc/handbook/porting.sgml @@ -1,414 +1,414 @@ -<!-- $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> Here are the guidelines one should follow in creating a new port for FreeBSD 2.x . This documentation will change as this process is progressively refined, so watch this space for details. The <tt>${..}</tt> variable names you see in this document all refer to various user-overridable defaults used (and documented) by <tt>/usr/share/mk/bsd.port.mk</tt>. Please refer to that file for more details. <sect1> <heading>Before starting the port</heading> <p> <em>Note: Only a fraction of the overridable variables are mentioned in this document. Most (if not all) are documented at the start of the <tt>bsd.port.mk</tt> file which can be found in /usr/share/mk. This file uses a non-standard tab setting. <tt>Emacs</tt> should recognise the setting on loading the file. <tt>vi</tt> or <tt>ex</tt> can be set to using the correct value by typing "<tt>:set tabstop=4</tt>" once the file has been loaded. - &a.gpalmer;</em> You may come across code that needs modifications or conditional compilation based upon what version of UNIX it's running under. If you need to make such changes to the code for conditional compilation, make sure you make the changes as general as possible so that we can back-port code to FreeBSD 1.x systems and cross-port to other BSD systems such as 4.4bsd from CSRG, BSD/386, 386BSD and NetBSD. The preferred way to tell 4.3BSD/Reno and newer versions of the BSD code apart is by using the "<tt>BSD</tt>" macro defined in <tt><sys/param.h></tt>. Hopefully that file is already included; if not, add the code: <tscreen><verb> #ifdef _HAVE_PARAM_H #include <sys/param.h> #endif </verb></tscreen> to the proper place in the <tt>.c</tt> file and add <tt>-D_HAVE_PARAM_H</tt> to the <tt>CFLAGS</tt> in the Makefile. Then, you may use: <tscreen><verb> #if (defined(BSD) && (BSD >= 199103)) </verb></tscreen> to detect if the code is being compiled on a 4.3 Net2 code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 1.0). Use: <tscreen><verb> #if (defined(BSD) && (BSD >= 199306)) </verb></tscreen> to detect if the code is being compiled on a 4.4 code base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 1.1). Use sparingly: <itemize> <item><tt>__FreeBSD__</tt> is defined in all versions of FreeBSD. Use it if the change you are making ONLY affects FreeBSD. Porting gotchas like the use of <tt>sys_errlist[]</tt> vs <tt>strerror()</tt> are Berkeleyisms, not FreeBSD changes. <item>In FreeBSD 2.x, <tt>__FreeBSD__</tt> is defined to be <tt>2</tt>. In earlier versions, it's <tt>1</tt>. <item>If you need to tell the difference between a FreeBSD 1.x system and a FreeBSD 2.x system, usually the right answer is to use the <tt>BSD</tt> macros described above. If there actually is a FreeBSD specific change (such as special shared library options when using '<tt>ld</tt>') then it's OK to use <tt>__FreeBSD__</tt> and "<tt>#if __FreeBSD_ > 1</tt>" to detect a FreeBSD 2.x system. </itemize> In the dozens of ports that have been done, there have only been one or two cases where <tt>__FreeBSD__</tt> should have been used. Just because an earlier port screwed up and used it in the wrong place doesn't mean you should do so too. <sect1> <heading> Doing the port</heading> <p>NOTE: If your sources work without change under FreeBSD, skip to the next section. <enum> <item>Get the original sources (normally) as a compressed tarball (<tt><foo>.tar.gz</tt> or <tt><foo>.tar.Z</tt>) and copy it into <tt>${DISTDIR}</tt>. Always use <em>mainstream</em> sources when and where you can, and don't be tempted to patch a tarball 2 or 3 revisions ahead just to save yourself trouble. The idea is that the ports collection should be usable even with all of <tt>${DISTDIR}</tt> blown away, which is to say that it should be possible for a user to repopulate all of <tt>${DISTDIR}</tt> with publically available files. <item>Unpack a copy of the tarball in a private directory and make whatever changes are necessary to get the port to compile properly under FreeBSD 2.0. Keep <em>careful track</em> of everything you do, as you will be automating the process shortly. Everything, including the deletion, addition or modification of files should be doable using an automated script or patch file when your port is finished. If your port requires significant user interaction/customization to compile or install, you should take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the new ports collection is to make each port as `plug-and-play' as possible for the end-user while using a minimum of disk space. <item>Carefully consider the list of patches, shell commands or user queries necessary for customizing the port, then, making sure you understand the following thoroughly, go for it. The sequence of events you need to understand is that which occurs when the user first types `<tt>make</tt>' in your port's directory, and you may find that having <tt>bsd.port.mk</tt> in another window while you read this really helps to understand it: Sequence of events: <enum> <item>The pre-fetch and fetch targets are run. The fetch target is responsible for making sure that the tarball exists locally in <tt>${DISTDIR}</tt>. The pre-fetch target hook is optional. If fetch cannot find the required files in <tt>${DISTDIR}</tt> it will look up the URL <tt>${MASTER_SITES}</tt>, which can be set in the Makefile or allowed to default to the Walnut Creek CDROM archive site. It will then attempt to fetch the named distribution file with <tt>${NCFTP}</tt>, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in <tt>${DISTDIR}</tt> for future use and proceed. <item>The pre-extract target hook, if it exists, is run. <item>The extract target, if not disabled, is run. It looks for your ports' distribution file in <tt>${DISTDIR}</tt> (typically a gzip'd tarball) and unpacks it into a temporary directory. <item>The pre-configure target hook is run. <item>The configure target is run. This can do any one of many different things. First, if any patches are found in the <tt>${PATCHDIR}</tt> subdirectory, they are applied at this time in alphabetical order. Next, a series of scripts, if detected, are run in the following order: <enum> <item><tt>${SCRIPTDIR}/pre-configure</tt> <item><tt>${SCRIPTDIR/configure</tt> or <tt>${WRKSRC}/configure</tt> if <tt>${HAS_CONFIGURE}</tt> is set. <item>If <tt>${USE_IMAKE}</tt> is set, an xmkmf command is done. <item><tt>${SCRIPTDIR}/post-configure</tt> </enum> As you can see, it's possible to do just about anything to your port, in a variety of stages! <item>The pre-build target hook is run. <item>The build target is run. This is responsible for decending into the ports' private working directory (<tt>${WRKSRC}</tt>) and building it. If <tt>${USE_GMAKE}</tt> is set, GNU <tt>make</tt> will be used, otherwise the system <tt>${MAKE}</tt>. </enum> <item>In the preparation of the port, files that have been added or changed can be picked up with a recursive diff for later feeding to patch. This is the easiest kind of change to make as it doesn't involve any mucking around with configuration files. Each set of patches you wish to apply should be collected into a file named "<tt>patch-<xx></tt>" where <tt><xx></tt> denotes the sequence in which the patches will be applied - these are done in <em>alphabetical order</em>, thus "<tt>aa</tt>" first, "<tt>ab</tt>" second and so on. These files should be stored in <tt>${PATCHDIR}</tt>, from where they will be automatically applied. All patches should be relative to <tt>${WRKSRC}</tt> (generally the directory your port's tarball unpacks itself into, that being where the make is done). <item>Include any additional customization commands to your `<tt>configure</tt>' script and save it to <tt>${SCRIPTDIR}/configure</tt>. Add your port to the Makefile one level above it so that it will be made automatically. <item>Always try to install relative to <tt>${PREFIX}</tt> in your Makefiles. This will normally be set to <tt>/usr/local</tt>, though it can be can be reassigned in your Makefile or in the users environment. Not hardcoding <tt>/usr/local</tt> anywhere in your installation will make the port much more flexible and cater to the needs of other sites. Note that this doesn't count for package `packing list' files since they have their own scheme for relocating themselves and can be left independant of <tt>${PREFIX}</tt> unless the package is one that hardcodes itself to a compiled-in location. <item>If your port requires user input to build, configure or install, then set <tt>IS_INTERACTIVE</tt> in your Makefile. This will allow "overnight builds" to progress past your port if the user sets the variable <tt>BATCH</tt> in his environment (and if the user sets the variable <tt>INTERACTIVE</tt>, then <em>only</em> those ports requiring interaction are built). For more details on any of this (since it may not be clear at first reading), examine an existing port and read the contents of <tt>/usr/share/mk/bsd.port.mk</tt>; you'll see that it's not as difficult as it sounds! </enum> <sect1> <heading>Configuring the Makefile</heading> <p>Configuring the Makefile is pretty simple, and again I suggest that you look at existing examples before starting. Consider the following problems in sequence as you design your new Makefile: <enum> <item>Does it live in <tt>${DISTDIR}</tt> as a standard gzip'd tarball? If so, you can go on to the next step. If not, you should look at overriding any of the <tt>${EXTRACT_CMD}</tt>, <tt>${EXTRACT_ARGS}</tt>, <tt>${EXTRACT_SUFX}</tt>, or <tt>${DISTFILE}</tt> variables, depending on how alien a format your port's distribution file is. In the worst case, you can simply create your own `<tt>extract</tt>' target to override the default, though this should be rarely, if ever, necessary. If you do find it necessary to do your own, your extract target should take care to "leave tracks" for itself so that files are not unnecessarily extracted twice---see the default extract rule in <tt>bsd.port.mk</tt> for an example of this. <item>If your port is integrated into the ports directory directly (original sources are already part of FreeBSD), you may also consider simply setting <tt>NO_EXTRACT</tt> and dispensing with the idea of a distribution file altogether. <item>You should set <tt>${DISTNAME}</tt> to be the base name of your port. The default rules expect the distribution file list (<tt>${DISTFILES}</tt>) to be named <tt>${DISTDIR}/${DISTFILE}${EXTRACT_SUFX}</tt> by default which, if it's a normal tarball, is going to be something like: <tscreen><verb> foozolix-1.0.tar.gz </verb></tscreen> For a setting of "<tt>DISTNAME=foozolix-1.0</tt>" The default rules also expect the tarball(s) to extract into a subdirectory called <tt>${WRKDIR}/${DISTNAME}</tt>, e.g. <tscreen><verb> "<blah>/foozolix-1.0/" </verb></tscreen> All this behavior can be overridden, of course, it simply represents the most common time-saving defaults. For a port requiring multiple distribution files, simply set <tt>${DISTFILES}</tt> explicitly. If only a subset of <tt>${DISTFILES}</tt> are actual extractable archives, then set them up in <tt>${EXTRACT_ONLY}</tt>, which will override the <tt>${DISTFILES}</tt> list when it comes to extraction. <item>If your package uses GNU <tt>make</tt>, set "<tt>USE_GMAKE=yes</tt>". If your package uses GNU <tt>configure</tt>, set "<tt>GNU_CONFIGURE=yes</tt>". If you want to override the default GNU <tt>configure</tt> arguments from `<tt>i386--freebsd</tt>' to something else, set those arguments in <tt>${GNU_CONFIGURE_ARGS}</tt>. If your package uses <tt>imake</tt> (e.g. is an X application that has an <tt>Imakefile</tt>), then set "<tt>USE_IMAKE=yes</tt>". This will cause the configure stage to automatically do an <tt>xmkmf</tt> and then a `<tt>make Makefiles</tt>'. <item>If you have a URL pointing at the the original tarball, record the directory containing the tarball in <tt>${MASTER_SITES}</tt>. This will provide a backup site, as well as a direct pointer to the original source location. The make macros will currently try to use this specification for grabbing the distribution file with <tt>${NCFTP}</tt> if they can't find it already on the system. See some of the other ports for examples. <item>Due to a problem in some of the ports, 2.0 was distributed with a setting which meant ports that have <tt>${USE_IMAKE}</tt> set do not install their manpages by default. Although -current has the logic reversed, for compatability with 2.0 systems (at least until 2.1 comes out) you should set "<tt>INSTALL_MANPAGES=yes</tt>". For complete forward compatability, if the port doesn't understand the "<tt>install.man</tt>" target, "<tt>NO_INSTALL_MANPAGES=yes</tt>" should be set (which conforms with the current logic in <tt>bsd.port.mk</tt>) <item>Don't forget to include <tt><bsd.port.mk></tt> at the bottom. That should do it! </enum> <sect1> <heading>Do's and Dont's</heading> <p><enum> <item>Don't leave anything valuable lying around in <tt>${WRKDIR}</tt>, `<tt>make clean</tt>' will <em>nuke</em> it completely! If you need auxilliary files that aren't scripts or patches, put them in <tt> ${FILESDIR}</tt>. <item>Do install package information, if possible. It would sure be nice if `<tt>make package</tt>' worked for the whole ports tree this time. <item>Do look at existing examples and the <tt>bsd.port.mk</tt> file before asking me questions! ;-) <item>Do ask me questions if you have any trouble! Don't just beat your head against a wall! :-) <item>Don't rely on custom utilities in your local configure script---they may not be there on the user's system! If you really need something else to be installed before you can work, detect this from your configure script, print a helpful message and exit with a non-zero status! At least you'll have given the user some idea of what's needed. If the custom utility or package is actually part of the ports tree, then set a pointer to it in your <tt>DEPENDS</tt> variable---the port structure will ensure that all <tt>DEPENDS</tt> targets are built first. <item>Do send applicable changes/patches to the original author/maintainer for inclusion in next release of the code. This will only make your job that much easier for the next release. </enum> diff --git a/share/doc/handbook/ports.sgml b/share/doc/handbook/ports.sgml index 23d9f2381bcd..526307d68d94 100644 --- a/share/doc/handbook/ports.sgml +++ b/share/doc/handbook/ports.sgml @@ -1,240 +1,240 @@ -<!-- $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> Unfortunately, there are more variations of UN*X than most people know of, and hence not all software for UN*X available on the Internet will work on all versions of UN*X (in fact, I can guarantee it!). Hence, some software needs modifications to work under some UN*Xs. The process of making those modifications is known as ``porting'' and the result known as a ``port'' (not to be confused with the sockets on the back of your computer!). <sect1><heading>What is the FreeBSD Ports Collection?</heading> <p> People who (allegedly) know what they are doing have automated the process of ``porting'' software to FreeBSD, and the result is the Ports Collection. The general idea is that a combination of various programming tools available in the base FreeBSD installation will allow you to fetch the port from a FreeBSD mirror site, type ``make'' and get the fully working program. The ports collection itself normally doesn't have any of the original source code necessary for the compilation in the tree, just those shell scripts, Makefiles and source code ``diffs'' that are necessary to compile the program under FreeBSD. This is meant to keep the entire system down to a manageable size, and the current system has over 100 ports in the master source tree, and yet a compressed tar file of that tree is about 2 megabytes (all the source code needed is over 100Mb's!). <sect1><heading>How does the system compile with no source code?</heading> <p> A ports' Makefile automatically looks in a central location on your system (usually /usr/ports/distfiles, though this value can be customized) for the associated set of original distribution files that have been ``ported''. These are generally provided at various places on the Internet, though if you have a CDROM distribution of FreeBSD then you've already got them available on your CD for ease of use. See section 3.1 if you have such a CD distribution, otherwise skip to section 3.2. <!-- 3.1 Compiling ports from CD Type something profound here. --> <sect2><heading>Compiling ports using an Internet connection</heading> <p> The ports collection can also use an auto-fetch system to keep your ports collection source tree up to date, updating the central ``distfiles'' version for you the next time you compile the port. Of course, this always assumes you have a permanent network link, or don't mind heavy usage of your telephone. If you don't want heavy network usage when you compile your ports tree, you can pre-fetch the necessary tarballs beforehand and put them into /usr/ports/distfiles (or wherever DISTDIR points) by hand. A good way to see what files a port is going to need is to cd to that port's directory and do a ``make -n fetch'' to see what it does. You can also chose to get the source files either from the master FTP site as defined in the relevant Makefile (in the MASTER_SITES line), or some FreeBSD mirror site also carrying a set of distfiles, as does the master FTP site on ftp.FreeBSD.org (aka ftp.cdrom.com) in the directory /pub/FreeBSD/ports/distfiles. Note that the files in that directory are not guarenteed to be kept up to date - this is a volunteer project! We can't make any guarantees about the mirror sites either - they are obviously under independant control and don't even have to mirror the distfiles directory. If you have a non-permanant link, you can fetch all the distfiles by going to the top of the tree and typing ``make fetch''. <sect1><heading>It doesn't work?!</heading> <p>Oh. You can do one of four (4) things : <enum> <item> Fix it yourself. Technical details can be found in the GUIDELINES file, available from URL ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES <item> Gripe. This is done by e-mail *ONLY*! The people at Walnut Creek are in no way responsible for the functionality (or lack thereof) of the FreeBSD system as a whole, and especially the ports system, which is mainly contributed by 3rd parties. (If you don't believe me, check the catalogue, especially the line saying "We cannot offer tech-support on this product") The e-mail address is Ports@FreeBSD.org. Please include details of the port, where you got both the port source & distfile(s) from, and what the error was. Note: At time of writing, lang/Sather doesn't seem to work on Pentium machines due to the Intel Curse (aka the Floating Point Division Bug). Please don't tell us about this - gripe to Intel instead - it's their bug! <item> Forget it. This is the easiest for most - very few of the programs in ports can be classed as `essential'! <item> Grab the pre-compiled package from a ftp server. The ``master'' package collection is in: ftp://ftp.FreeBSD.org/pub/FreeBSD/packages/ though check your local mirror first, please! These are more likely to work (on the whole) than trying to compile from source, and a lot faster! </enum> <sect1><heading>I've ported a program and I want to make a port out of it. What now?</heading> <p> See the file GUIDELINES, in: ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/GUIDELINES This contains details of the procedure and structure involved. <sect1><heading>I've got a good port, what now?</heading> <p> Upload the fixed version to freefall.cdrom.com /pub/incoming or ftp.FreeBSD.org /pub/FreeBSD/incoming and send e-mail to ports@FreeBSD.org with the filename and details. Someone on the all-volunteer `ports committee' will (hopefully) look it over and commit it to the ports collection if they like the looks of it. <sect1><heading>Things go funny during the fetch stage of compilation!</heading> <p> We know. Please don't blame us. There is a program called `ncftp' which is used instead of the normal ftp as it can do so-called ``background'' or ``batch'' transfers, ideal for this situation. Unfortunately it can do strange things, and has crashed at least one machine (during circumstances stranger than most, I'll admit, but it was still responsible). Hopefully a future release of ncftp will fix these problems (it is not maintained by the main FreeBSD team, but a third party, who is I believe aware of its shortcomings) <sect1><heading>I want to leave the compile going overnight, but some ports don't like this.</heading> <p> There is a way around this. Before starting the compilation, type: <verb> setenv BATCH yes # (if you use csh/tcsh) or BATCH=yes # (for sh/bash) </verb> This should miss out ports which need user interaction. Unfortunately, ncftp doesn't know about this trick, and can often screw up and ask stupid questions in unattended batch mode. See (7). To compile those ports left out by doing the above, using a different login shell (or unsetting the above BATCH variable), set the INTERACTIVE variable instead (you can use the same statements as above except replace ``BATCH'' with ``INTERACTIVE'') and re-run make. This should now compile only those ports which will definitely ask for user interaction. <sect1><heading>The ports collection is weak. What can I do to help?</heading> <p> First read the bsd.port.mk file (which may be found in /usr/share/mk/) and the associated bsd.port.subdir.mk file. A lot of the weirdness can be explained properly in there (most of the current weirdness is due to the lack of assumptions about anything, which is necessary due to the generic nature of these files). Also check that you have an up-to-date copy, as the file can change from minute to minute. A reasonably up-to-date copy can be found in: <url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk"> If you find that you still need to go in there and alter things, by all means do so, and then send the diffs to ports@FreeBSD.org if you'd like them to be a part of the default distribution. Please also remember that any changes must respect backwards-compatability with any and all older Makefiles, unless you want a real nightmare of /usr/ports munging ahead of you! Large scale changes will generally not be warmly welcomed unless all the existing makefiles work without alteration. Sorry! <sect1><heading>This FAQ is weak. What can I do?</heading> <p> Send changes to ports@FreeBSD.org. Changes are most welcome! This FAQ is also very green and should be considered no more than a `good start' for now. Authors? You can come out of hiding any time now! :-) <sect1><heading>How do I get more information on all the ports?</heading> <p> One good method is to cd to the top of the ports tree (say /usr/ports) and type something like: <verb> make describe | sed -e '/===/D' -e 's;/usr/ports/;;' | expand -40 </verb> The ``make describe'' will try to extract the one-line description from each port, and the ``sed'' will delete the extraneous output. ``expand'' just makes it a little more readable (sort of - you may want to season the output of this more to taste). <sect1><heading>I've heard of a new checksum system. What is this for?</heading> <p> For various reasons, when using FTP over the Internet to obtain the source code, you may not always end up with the same copy of the code that the origional porter worked from, and this can lead to problems. So a simple checksumming system has been employed to try and highlight problems in this area. To check the entire system, go to the top of the ports tree (defaults to /usr/ports) and type <verb> make checksum </verb> This will give a report on the validity of the files you have FTP'd. If some are missing, the system will attempt to retrieve them before running the checksum routine. The same technique can be applied to a single port. The system will complain if there is no pre-computed checksum available for that port. Not all ports currently have checksums, but this should be cured soon. Some older versions of the system don't recognise the ``checksum'' target. In that case, try the command <verb> make check-md5 </verb> (``check-md5'' was the pre-cursor to the ``checksum'' target). If neither work, get the latest copies of bsd.port.mk and bsd.port.subdir.mk from <url url="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/src/share/mk"> and install them in /usr/share/mk. This will get you the latest version of the ports system. diff --git a/share/doc/handbook/submitters.sgml b/share/doc/handbook/submitters.sgml index eefc21abd4e5..81188ae8148c 100644 --- a/share/doc/handbook/submitters.sgml +++ b/share/doc/handbook/submitters.sgml @@ -1,181 +1,237 @@ -<!-- $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> <p><em>Contributed by &a.jkh;.</em> This guide is intended for those who are moderately familar with FreeBSD and are now to the point where they have some locally developed 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. <sect><heading>Ideas and suggestions</heading> <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 <hackers@freebsd.org>. Likewise, people with an interest - in such things (and a tolerance for a HIGH volume of mail!) may - subscribe by sendimg mail to <majordomo@freebsd.org>. See also the - file /usr/share/FAQ/mailing-list.FAQ. - - <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 idea or suggestion of general technical interest should be + mailed to <tt><hackers@freebsd.org></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><majordomo@freebsd.org></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 + <tt>send-pr(1)</tt> program. This will prompt you for various fields to fill in. Simply go to the fields - surrounded by <>'s and fill in your own information in place of + surrounded by <tt><></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: - - <bugs@freebsd.org> + reason, unable to use the <tt>send-pr(1)</tt> command, + then you may also file a bug report by sending mail to + <tt><bugs@freebsd.org></tt>. </itemize> <sect><heading>Changes to the existing code</heading> <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 - <announce@freebsd.org> mailing list (among others) where periodic + <tt><announce@freebsd.org></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 <oldfile> <newfile> or diff -c -r <olddir> <newdir>). - - 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 <hackers@freebsd.org>. 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 <hackers@freebsd.org>. See the man pages - on tar and uuencode 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 <core@freebsd.org> rather than <hackers@freebsd.org>. 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. + 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 <oldfile> <newfile> +</verb></tscreen> +or +<tscreen><verb> +diff -c -r <olddir> <newdir> +</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 + <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><hackers@freebsd.org></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 + <tt>tar</tt> file and running the <tt>uuencode(1)</tt> program + on it before sending the output of that to + <tt><hackers@freebsd.org></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, 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><core@freebsd.org></tt> rather than + <tt><hackers@freebsd.org></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: - - <url url="ftp://freefall.cdrom.com/pub/FreeBSD/incoming"> +<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. - 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 authors are always free to make the changes available through 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. - - 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 - <ports@freebsd.org>. - - -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 +<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><ports@freebsd.org></tt>. + +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!