diff options
Diffstat (limited to 'en/handbook/kernelopts/chapter.sgml')
| -rw-r--r-- | en/handbook/kernelopts/chapter.sgml | 173 |
1 files changed, 0 insertions, 173 deletions
diff --git a/en/handbook/kernelopts/chapter.sgml b/en/handbook/kernelopts/chapter.sgml deleted file mode 100644 index 0e6defe0cb..0000000000 --- a/en/handbook/kernelopts/chapter.sgml +++ /dev/null @@ -1,173 +0,0 @@ - <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 - <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 “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, <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><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. <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 <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: ---> - |