diff options
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.sgml | 162 |
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><arch></replaceable>/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 - 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>.<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 -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: ("../book.sgml" "part" "chapter") - End: ---> - |