10b0b0a21e
most of the other spurious comments. Two comments relating to copyright have *not* been merged in from the LinuxDoc version yet -- I've contacted the original authors to ask if they would be willing to assign the copyright to the project. When I get their response the copyright comments will either be merged in, or left out, as necessary.
164 lines
7.6 KiB
Text
164 lines
7.6 KiB
Text
<!--
|
|
The FreeBSD Documentation Project
|
|
|
|
$Id: chapter.sgml,v 1.9 1999-03-08 22:04:43 nik 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 “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 <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 must have been made overridable 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 “config option” 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/i386/conf/options.<replaceable><arch></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
|
|
behaviour 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>.<arch></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 -name
|
|
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 <xxx.h></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: ("../handbook.sgml" "part" "chapter")
|
|
End:
|
|
-->
|
|
|