aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml')
-rw-r--r--en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml162
1 files changed, 0 insertions, 162 deletions
diff --git a/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml b/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
deleted file mode 100644
index 1e91b5cae7..0000000000
--- a/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml
+++ /dev/null
@@ -1,162 +0,0 @@
-<!--
- The FreeBSD Documentation Project
-
- $FreeBSD: doc/en_US.ISO_8859-1/books/handbook/kernelopts/chapter.sgml,v 1.16 2000/06/14 00:47:36 jim Exp $
--->
-
-<chapter id="kernelopts">
- <title>Adding New Kernel Configuration Options</title>
-
- <para><emphasis>Contributed by &a.joerg;</emphasis></para>
-
- <note>
- <para>You should be familiar with the section about <link
- linkend="kernelconfig">kernel configuration</link> before reading
- here.</para>
- </note>
-
- <sect1>
- <title>What's a <emphasis>Kernel Option</emphasis>, Anyway?</title>
-
- <para>The use of kernel options is basically described in the <link
- linkend="kernelconfig-options">kernel configuration</link> section.
- There's also an explanation of <quote>historic</quote> and
- <quote>new-style</quote> 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 <command>make depend</command> in their
- kernel compile directory after running
- &man.config.8;, the build process will automatically pick up modified
- options, and only recompile those files where it is necessary. Wiping
- out the old compile directory on each run of &man.config.8; as it is
- still done now can then be eliminated again.</para>
-
- <para>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 <filename>.h</filename> file) must be written with the option
- concept in mind, i.e., the default can be overridden by the
- config option. This is usually done with something like:</para>
-
- <programlisting>#ifndef THIS_OPTION
-#define THIS_OPTION (some_default_value)
-#endif /* THIS_OPTION */</programlisting>
-
- <para>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. Clearly, 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.</para>
-
- <para>It is also possible to create value-less options that simply enable
- or disable a particular piece of code by embracing it in</para>
-
- <programlisting>#ifdef THAT_OPTION
-
-[your code here]
-
-#endif</programlisting>
-
- <para>Simply mentioning <literal>THAT_OPTION</literal> in the config file
- (with or without any value) will then turn on the corresponding piece of
- code.</para>
-
- <para>People familiar with the C language will immediately recognize that
- everything could be counted as a <quote>config option</quote> where there
- is at least a single <literal>#ifdef</literal> referencing it...
- However, it's unlikely that many people would put</para>
-
- <programlisting>options notyet,notdef</programlisting>
-
- <para>in their config file, and then wonder why the kernel compilation
- falls over. <!-- smiley -->:-)</para>
-
- <para>Clearly, using arbitrary names for the options makes it very hard to
- track their usage throughout the kernel source tree. That is the
- rationale behind the <emphasis>new-style</emphasis> option scheme, where
- each option goes into a separate <filename>.h</filename> file in the
- kernel compile directory, which is by convention named
- <filename>opt_<replaceable>foo</replaceable>.h</filename>. This way,
- the usual Makefile dependencies could be applied, and
- <command>make</command> can determine what needs to be recompiled once
- an option has been changed.</para>
-
- <para>The old-style option mechanism still has one advantage for local
- options or maybe experimental options that have a short anticipated
- lifetime: since it is easy to add a new <literal>#ifdef</literal> to the
- kernel source, this has already made it a kernel config option. In this
- case, the administrator using such an option is responsible himself for
- knowing about its implications (and maybe manually forcing the
- recompilation of parts of his kernel). Once the transition of all
- supported options has been done, &man.config.8; will warn whenever an
- unsupported option appears in the config file, but it will nevertheless
- include it into the kernel Makefile.</para>
- </sect1>
-
- <sect1>
- <title>Now What Do I Have to Do for it?</title>
-
- <para>First, edit <filename>sys/conf/options</filename> (or
- <filename>sys/<replaceable>&lt;arch&gt;</replaceable>/conf/options.<replaceable>&lt;arch&gt;</replaceable></filename>,
- e. g. <filename>sys/i386/conf/options.i386</filename>), and select an
- <filename>opt_<replaceable>foo</replaceable>.h</filename> file where
- your new option would best go into.</para>
-
- <para>If there is already something that comes close to the purpose of the
- new option, pick this. For example, options modifying the overall
- behavior of the SCSI subsystem can go into
- <filename>opt_scsi.h</filename>. By default, simply mentioning an
- option in the appropriate option file, say <literal>FOO</literal>,
- implies its value will go into the corresponding file
- <filename>opt_foo.h</filename>. This can be overridden on the
- right-hand side of a rule by specifying another filename.</para>
-
- <para>If there is no
- <filename>opt_<replaceable>foo</replaceable>.h</filename> already
- available for the intended new option, invent a new name. Make it
- meaningful, and comment the new section in the
- <filename>options[<replaceable>.&lt;arch&gt;</replaceable>]</filename>
- file. &man.config.8; will automagically pick up the change, and create
- that file next time it is run. Most options should go in a header file
- by themselves..</para>
-
- <para>Packing too many options into a single
- <filename>opt_<replaceable>foo</replaceable>.h</filename> will cause too
- many kernel files to be rebuilt when one of the options has been changed
- in the config file.</para>
-
- <para>Finally, find out which kernel files depend on the new option.
- Unless you have just invented your option, and it does not exist
- anywhere yet, <screen>
-&prompt.user; <userinput>find /usr/src/sys -type f | xargs fgrep NEW_OPTION</userinput>
-</screen>
- is your friend in finding them. Go and edit all those files, and add
- <programlisting>#include "opt_foo.h"</programlisting> <emphasis>on
- top</emphasis> before all the <literal>#include &lt;xxx.h&gt;</literal> stuff.
- This sequence is most important as the options could override defaults
- from the regular include files, if the defaults are of the form
- <programlisting> #ifndef NEW_OPTION #define NEW_OPTION (something)
- #endif</programlisting> in the regular header.</para>
-
- <para>Adding an option that overrides something in a system header file
- (i.e., a file sitting in <filename>/usr/include/sys/</filename>) is
- almost always a mistake.
- <filename>opt_<replaceable>foo</replaceable>.h</filename> cannot be
- included into those files since it would break the headers more
- seriously, but if it is not included, then places that include it may
- get an inconsistent value for the option. Yes, there are precedents for
- this right now, but that does not make them more correct.</para>
- </sect1>
-</chapter>
-
-<!--
- Local Variables:
- mode: sgml
- sgml-declaration: "../chapter.decl"
- sgml-indent-data: t
- sgml-omittag: nil
- sgml-always-quote-attributes: t
- sgml-parent-document: ("../book.sgml" "part" "chapter")
- End:
--->
-