<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->

<chapter id="kernelopts">
  <chapterinfo>
    <authorgroup>
      <author>
	<firstname>J&ouml;rg</firstname>
	<surname>Wunsch</surname>
	<contrib>Contributed by </contrib>
      </author>
    </authorgroup>
  </chapterinfo>

  <title>Adding New Kernel Configuration Options</title>
  
  <note>
    <para>You should be familiar with the section about <link
	linkend="kernelconfig">kernel configuration</link> before reading
      here.</para>
  </note>
  
  <sect1>
    <title>What is 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 is 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 is 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.</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:
-->

