diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml index bf4aa5c04e..322c50d932 100644 --- a/en_US.ISO8859-1/books/handbook/book.sgml +++ b/en_US.ISO8859-1/books/handbook/book.sgml @@ -1,213 +1,209 @@ %man; %bookinfo; %freebsd; %chapters; %authors; %teams; %mailing-lists; %newsgroups; %txtfiles; - - %pgpkeys; ]> FreeBSD Handbook The FreeBSD Documentation Project February 1999 1995 1996 1997 1998 1999 2000 2001 2002 2003 The FreeBSD Documentation Project &bookinfo.trademarks; &bookinfo.legalnotice; Welcome to FreeBSD! This handbook covers the installation and day to day use of FreeBSD &rel2.current;-RELEASE and FreeBSD &rel.current;-RELEASE. This manual is a work in progress and is the work of many individuals. 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 the &a.doc;. The latest version of this document is always available from the FreeBSD web site. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. If you would prefer to have a hard copy of the handbook, you can purchase one at the FreeBSD Mall. You may also want to search the handbook. &chap.preface; Getting Started This part of the FreeBSD Handbook is for users and administrators who are new to FreeBSD. These chapters: Introduce you to FreeBSD. Guide you through the installation process. Teach you some Unix basics. Show you how to install the wealth of third party applications available for FreeBSD. Introduce you to X, the Unix windowing system, and detail how to configure a desktop environment that makes you more productive. We have tried to keep the number of forward references in the text to a minimum so that you can read this section of the Handbook from front to back with the minimum of page flipping required. System Administration The remaining chapters of the FreeBSD Handbook cover all aspects of FreeBSD system administration. Each chapter starts by describing what you will learn as a result of reading the chapter, and also details what you are expected to know before tackling the material. These chapters are designed to be read when you need the information. You do not have to read them in any particular order, nor do you need to read all of them before you can begin using FreeBSD. - - Appendices &chap.colophon; diff --git a/en_US.ISO8859-1/books/handbook/policies/Makefile b/en_US.ISO8859-1/books/handbook/policies/Makefile deleted file mode 100644 index 0dd403f15f..0000000000 --- a/en_US.ISO8859-1/books/handbook/policies/Makefile +++ /dev/null @@ -1,15 +0,0 @@ -# -# Build the Handbook with just the content from this chapter. -# -# $FreeBSD$ -# - -CHAPTERS= policies/chapter.sgml - -VPATH= .. - -MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} - -DOC_PREFIX?= ${.CURDIR}/../../../.. - -.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml b/en_US.ISO8859-1/books/handbook/policies/chapter.sgml deleted file mode 100644 index b6c9b5fe2e..0000000000 --- a/en_US.ISO8859-1/books/handbook/policies/chapter.sgml +++ /dev/null @@ -1,436 +0,0 @@ - - - - - - Poul-Henning - Kamp - Contributed by - - - - Source Tree Guidelines and Policies - - This chapter documents various guidelines and policies in force for - the FreeBSD source tree. - - - <makevar>MAINTAINER</makevar> on Makefiles - ports maintainer - - June 1996. - - If a particular portion of the FreeBSD distribution is being - maintained by a person or group of persons, they can communicate this - fact to the world by adding a - - MAINTAINER= email-addresses - - line to the Makefiles covering this portion of the - source tree. - - The semantics of this are as follows: - - The maintainer owns and is responsible for that code. This means - that he is responsible for fixing bugs and answer problem reports - pertaining to that piece of the code, and in the case of contributed - software, for tracking new versions, as appropriate. - - Changes to directories which have a maintainer defined shall be sent - to the maintainer for review before being committed. Only if the - maintainer does not respond for an unacceptable period of time, to - several emails, will it be acceptable to commit changes without review - by the maintainer. However, it is suggested that you try to have the - changes reviewed by someone else if at all possible. - - It is of course not acceptable to add a person or group as - maintainer unless they agree to assume this duty. On the other hand it - does not have to be a committer and it can easily be a group of - people. - - - - - - - Poul-Henning - Kamp - Contributed by - - - David - O'Brien - - - - - - Contributed Software - - contributed software - - Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this contributed software. Some - examples are perl, gcc and - patch. - - Over the last couple of years, various methods have been used in - dealing with this type of software and all have some number of - advantages and drawbacks. No clear winner has emerged. - - Since this is the case, after some debate one of these methods has - been selected as the official method and will be required - for future imports of software of this kind. Furthermore, it is - strongly suggested that existing contributed software converge on this - model over time, as it has significant advantages over the old method, - including the ability to easily obtain diffs relative to the - official versions of the source by everyone (even without - cvs access). This will make it significantly easier to return changes - to the primary developers of the contributed software. - - Ultimately, however, it comes down to the people actually doing the - work. If using this model is particularly unsuited to the package being - dealt with, exceptions to these rules may be granted only with the - approval of the core team and with the general consensus of the other - developers. The ability to maintain the package in the future will be a - key issue in the decisions. - - - Because of some unfortunate design limitations with the RCS file - format and CVS's use of vendor branches, minor, trivial and/or - cosmetic changes are strongly discouraged on - files that are still tracking the vendor branch. Spelling - fixes are explicitly included here under the - cosmetic category and are to be avoided for files with - revision 1.1.x.x. The repository bloat impact from a single character - change can be rather dramatic. - - - The Tcl embedded programming - language will be used as example of how this model works: - - src/contrib/tcl contains the source as - distributed by the maintainers of this package. Parts that are entirely - not applicable for FreeBSD can be removed. In the case of Tcl, the - mac, win and - compat subdirectories were eliminated before the - import - - src/lib/libtcl contains only a "bmake style" - Makefile that uses the standard - bsd.lib.mk makefile rules to produce the library - and install the documentation. - - src/usr.bin/tclsh contains only a - bmake style - Makefile which will produce and install the - tclsh program and its associated man-pages using the - standard bsd.prog.mk rules. - - src/tools/tools/tcl_bmake contains a couple of - shell-scripts that can be of help when the Tcl software needs updating. - These are not part of the built or installed software. - - The important thing here is that the - src/contrib/tcl directory is created according to - the rules: It is supposed to contain the sources as distributed (on a - proper CVS vendor-branch and without RCS keyword expansion) with as few - FreeBSD-specific changes as possible. The 'easy-import' tool on - freefall will assist in doing the import, but if there - are any doubts on - how to go about it, it is imperative that you ask first and not blunder - ahead and hope it works out. CVS is not forgiving of - import accidents and a fair amount of effort is required to back out - major mistakes. - - Because of the previously mentioned design limitations with CVS's - vendor branches, it is required that official patches from - the vendor be applied to the original distributed sources and the result - re-imported onto the vendor branch again. Official patches should never - be patched into the FreeBSD checked out version and "committed", as this - destroys the vendor branch coherency and makes importing future versions - rather difficult as there will be conflicts. - - Since many packages contain files that are meant for compatibility - with other architectures and environments that FreeBSD, it is - permissible to remove parts of the distribution tree that are of no - interest to FreeBSD in order to save space. Files containing copyright - notices and release-note kind of information applicable to the remaining - files shall not be removed. - - If it seems easier, the bmake - Makefiles can be produced from the dist tree - automatically by some utility, something which would hopefully make it - even easier to upgrade to a new version. If this is done, be sure to - check in such utilities (as necessary) in the - src/tools directory along with the port itself so - that it is available to future maintainers. - - In the src/contrib/tcl level directory, a file - called FREEBSD-upgrade should be added and it - should states things like: - - - - Which files have been left out - - - - Where the original distribution was obtained from and/or the - official master site. - - - - Where to send patches back to the original authors - - - - Perhaps an overview of the FreeBSD-specific changes that have - been made. - - - - However, please do not import FREEBSD-upgrade - with the contributed source. Rather you should cvs add - FREEBSD-upgrade ; cvs ci after the initial import. Example - wording from src/contrib/cpio is below: - - This directory contains virgin sources of the original distribution files -on a "vendor" branch. Do not, under any circumstances, attempt to upgrade -the files in this directory via patches and a cvs commit. New versions or -official-patch versions must be imported. Please remember to import with -"-ko" to prevent CVS from corrupting any vendor RCS Ids. - -For the import of GNU cpio 2.4.2, the following files were removed: - - INSTALL cpio.info mkdir.c - Makefile.in cpio.texi mkinstalldirs - -To upgrade to a newer version of cpio, when it is available: - 1. Unpack the new version into an empty directory. - [Do not make ANY changes to the files.] - - 2. Remove the files listed above and any others that don't apply to - FreeBSD. - - 3. Use the command: - cvs import -ko -m 'Virgin import of GNU cpio v<version>' \ - src/contrib/cpio GNU cpio_<version> - - For example, to do the import of version 2.4.2, I typed: - cvs import -ko -m 'Virgin import of GNU v2.4.2' \ - src/contrib/cpio GNU cpio_2_4_2 - - 4. Follow the instructions printed out in step 3 to resolve any - conflicts between local FreeBSD changes and the newer version. - -Do not, under any circumstances, deviate from this procedure. - -To make local changes to cpio, simply patch and commit to the main -branch (aka HEAD). Never make local changes on the GNU branch. - -All local changes should be submitted to "cpio@gnu.ai.mit.edu" for -inclusion in the next vendor release. - -obrien@FreeBSD.org - 30 March 1997 - - - - Encumbered Files - - It might occasionally be necessary to include an encumbered file in - the FreeBSD source tree. For example, if a device requires a small - piece of binary code to be loaded to it before the device will operate, - and we do not have the source to that code, then the binary file is said - to be encumbered. The following policies apply to including encumbered - files in the FreeBSD source tree. - - - - Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered. - - - - Any file with a license more restrictive than BSD or GNU is - encumbered. - - - - A file which contains downloadable binary data for use by the - hardware is not encumbered, unless (1) or (2) apply to it. It must - be stored in an architecture neutral ASCII format (file2c or - uuencoding is recommended). - - - - Any encumbered file requires specific approval from the Core team before it is added to the - CVS repository. - - - - Encumbered files go in src/contrib or - src/sys/contrib. - - - - The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code. - - - - Object files are named - arch/filename.o.uu>. - - - - Kernel files: - - - - Should always be referenced in - conf/files.* (for build simplicity). - - - - Should always be in LINT, but the Core team decides per case if it - should be commented out or not. The Core team can, of course, change - their minds later on. - - - - The Release Engineer - decides whether or not it goes into the release. - - - - - - User-land files: - - - - core team - The Core team decides if - the code should be part of make world. - - - - release engineer - The Release Engineer - decides if it goes into the release. - - - - - - - - - - - Satoshi - Asami - Contributed by - - - Peter - Wemm - - - David - O'Brien - - - - - - Shared Libraries - - If you are adding shared library support to a port or other piece of - software that does not have one, the version numbers should follow these - rules. Generally, the resulting numbers will have nothing to do with - the release version of the software. - - The three principles of shared library building are: - - - - Start from 1.0 - - - - If there is a change that is backwards compatible, bump minor - number (note that ELF systems ignore the minor number) - - - - If there is an incompatible change, bump major number - - - - For instance, added functions and bugfixes result in the minor - version number being bumped, while deleted functions, changed function - call syntax etc. will force the major version number to change. - - Stick to version numbers of the form major.minor - (x.y). Our a.out - dynamic linker does not handle version numbers of the form - x.y.z - well. Any version number after the y - (ie. the third digit) is totally ignored when comparing shared lib - version numbers to decide which library to link with. Given two shared - libraries that differ only in the micro revision, - ld.so will link with the higher one. Ie: if you link - with libfoo.so.3.3.3, the linker only records - 3.3 in the headers, and will link with anything - starting with - libfoo.so.3.(anything >= - 3).(highest - available). - - - ld.so will always use the highest - minor revision. Ie: it will use - libc.so.2.2 in preference to - libc.so.2.0, even if the program was initially - linked with libc.so.2.0. - - - In addition, our ELF dynamic linker does not handle minor version - numbers at all. However, one should still specify a major and minor - version number as our Makefiles "do the right thing" - based on the type of system. - - For non-port libraries, it is also our policy to change the shared - library version number only once between releases. In addition, it is - our policy to change the major shared library version number only once - between major OS releases. Ie: X.0 to (X+1).0. When you make a - change to a system library that requires the version number to be - bumped, check the Makefile's commit logs. It is the - responsibility of the committer to ensure that the first such change - since the release will result in the shared library version number in - the Makefile to be updated, and any subsequent - changes will not. - - - -