doc/en/handbook/kernelopts/chapter.sgml

    <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 &ldquo;historic&rdquo; and
	  &ldquo;new-style&rdquo; 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
	  <citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry>, 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
	  <citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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 &ldquo;config option&rdquo; 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, <citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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>&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 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>.&lt;arch&gt;</replaceable>]</filename> file. <citerefentry><refentrytitle>config</refentrytitle><manvolnum>8</manvolnum></citerefentry> 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,
	
	<informalexample>
	  <screen>&prompt.user; <userinput>find /usr/src/sys -name type f | xargs fgrep NEW_OPTION</userinput></screen>
	</informalexample>
	
	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: ("../handbook.sgml" "part" "chapter")
     End:
-->