diff --git a/share/doc/handbook/Makefile b/share/doc/handbook/Makefile index 76c78df2e239..a390677c3412 100644 --- a/share/doc/handbook/Makefile +++ b/share/doc/handbook/Makefile @@ -1,4 +1,4 @@ -# $Id: Makefile,v 1.19 1996/11/28 18:09:24 jfieber Exp $ +# $Id: Makefile,v 1.20 1996/12/19 20:24:36 jkh Exp $ SRCS= authors.sgml basics.sgml bibliography.sgml boothelp.sgml SRCS+= booting.sgml contrib.sgml crypt.sgml ctm.sgml current.sgml cvsup.sgml @@ -6,7 +6,7 @@ SRCS+= cyclades.sgml development.sgml dialup.sgml dialout.sgml SRCS+= diskless.sgml dma.sgml eresources.sgml esdi.sgml SRCS+= firewalls.sgml glossary.sgml goals.sgml SRCS+= handbook.sgml history.sgml hw.sgml install.sgml isdn.sgml -SRCS+= kerberos.sgml kernelconfig.sgml kerneldebug.sgml +SRCS+= kerberos.sgml kernelconfig.sgml kerneldebug.sgml kernelopts.sgml SRCS+= lists.sgml mail.sgml memoryuse.sgml SRCS+= mirrors.sgml nfs.sgml nutshell.sgml pgpkeys.sgml policies.sgml SRCS+= porting.sgml ports.sgml ppp.sgml printing.sgml diff --git a/share/doc/handbook/handbook.sgml b/share/doc/handbook/handbook.sgml index f3ce00699623..eeb19f02f210 100644 --- a/share/doc/handbook/handbook.sgml +++ b/share/doc/handbook/handbook.sgml @@ -1,4 +1,4 @@ - + or one of the numerous &submitters; &troubleshooting; &kerneldebug; + &kernelopts; &linuxemu; FreeBSD internals &booting; diff --git a/share/doc/handbook/kernelconfig.sgml b/share/doc/handbook/kernelconfig.sgml index fe0597dade81..72b46c93b040 100644 --- a/share/doc/handbook/kernelconfig.sgml +++ b/share/doc/handbook/kernelconfig.sgml @@ -1,4 +1,4 @@ - + Configuring the FreeBSD Kernel @@ -135,19 +135,19 @@ The Configuration File -

The general format of a configuration file is quite - simple. Each line contains a keyword and one or more - arguments. For simplicity, most lines only contain one - argument. Anything following a # is considered - a comment and ignored. The following sections describe - each keyword, generally in the order they are listed in - GENERIC, although some related keywords have been grouped - together in a single section (such as Networking) even - though they are actually scattered throughout the GENERIC - file. An exhaustive list of options and more detailed explanations +

The general format of a configuration file is quite simple. + Each line contains a keyword and one or more arguments. For + simplicity, most lines only contain one argument. Anything + following a # is considered a comment and ignored. + The following sections describe each keyword, generally in the + order they are listed in GENERIC, although some related + keywords have been grouped together in a single section (such + as Networking) even though they are actually scattered + throughout the GENERIC file.

The kernel is currently being moved to a better organization of the option handling. Traditionally, each option in the diff --git a/share/doc/handbook/kernelopts.sgml b/share/doc/handbook/kernelopts.sgml new file mode 100644 index 000000000000..5f4670fb5b4b --- /dev/null +++ b/share/doc/handbook/kernelopts.sgml @@ -0,0 +1,149 @@ + + + + +Adding New Kernel Configuration Options + +

Contributed by &a.joerg; + + before reading here. + +What's a kernel option, anyway? + +

The use of kernel options is basically described in the section. + There's also an explanation about ``historic'' and ``new-style'' + options. The ultimate goal is to eventually turn all the supported + options in the kernel into new-style ones, so for people who + correctly did a Basically, a kernel option is nothing else than the definition of + a C preprocessor macro for the kernel compilation process. To make + the build truly optional, the corresponding part of the kernel + source (or kernel +#ifndef THIS_OPTION +#define THIS_OPTION (some_default_value) +#endif /* THIS_OPTION */ + +

This way, an administrator mentioning another value for the + option in his config file will take the default out of effect, and + replace it with his new value. Apparently, the new value will be + substituted into the source code during the preprocessor run, so it + must be a valid C expression in whatever context the default value + would have been used. + +

It's also possible to create value-less options that simply + enable or disable a particular piece of code by embracing it in + + +#ifdef THAT_OPTION + +... + +#endif + +

Simply mentioning People familiar with the C language will immediately recognize + that everything could be counted as a ``config option'' where + there's at least a single + options notyet,notdef + +

in their config file however, and watch the kernel compilation + fall over. :-) + +

Apparently, using arbitrary names for the options makes it very + hard to track their usage throughout the kernel source tree. That's + the rationale behind the opt_foo.h. + This way, the usual Makefile dependencies could be applied, and + The old-style option mechanism still has one advantage for local + options or maybe experimental options that have a short anticipated + lifetime: since it's easy to add a new Now what do I have to do for it? + +

First, edit sys/conf/options (or + sys/i386/conf/options.<arch>, e. g. + sys/i386/conf/options.i386), and select an + opt_foo.h file where your new option would best go + into. + +

If there's already something that comes close to the purpose of + the new option, pick this. For example, options modifying the + overall behaviour of the SCSI subsystem can go into If there's no opt_foo.h already available for + the intended new option, invent a new name. Make it meaningful, and + comment the new section in the + options[.<arch>] file. Packing too many options into a single + opt_foo.h will cause too many kernel files to be + rebuilt when one of the options has been changed in the config file. + +

Finally, find out which kernel files depend on the new option. + Unless you've just invented your option, so it doesn't exist + anywhere yet, + + + find /usr/src/sys -name type f | xargs fgrep NEW_OPTION + +

is your friend in finding them. Go and edit all those files, and + add + + +#include "opt_foo.h" + +

on top, before all the +#ifndef NEW_OPTION +#define NEW_OPTION (something) +#endif + +

in the regular header. + +

Adding an option that overrides something in a system header file + (i. e., a file sitting in /usr/include/sys/) is almost + always a mistake. opt_foo.h cannot be included + into those files since it would break the headers more seriously, + but if it isn't included, then places that include it may get an + inconsistent value for the option. Yes, there are precedents for + this right now, but that doesn't make them more correct. diff --git a/share/doc/handbook/sections.sgml b/share/doc/handbook/sections.sgml index ed2f3b5e27b4..c5fa32e07733 100644 --- a/share/doc/handbook/sections.sgml +++ b/share/doc/handbook/sections.sgml @@ -1,4 +1,4 @@ - + @@ -31,6 +31,7 @@ +