Add a skeletal kernconf(5) manual page for documenting the structure
authorSascha Wildner <swildner@dragonflybsd.org>
Thu, 13 Sep 2007 20:02:52 +0000 (20:02 +0000)
committerSascha Wildner <swildner@dragonflybsd.org>
Thu, 13 Sep 2007 20:02:52 +0000 (20:02 +0000)
of a kernel configuration file.

It only documents the keywords for now but can (and will eventually)
be extended to document our numerous kernel options.

It's kinda based on NetBSD's options(4).

Suggested-by: dillon (sort of)
[http://leaf.dragonflybsd.org/mailarchive/bugs/2007-08/msg00064.html]

share/man/man5/Makefile
share/man/man5/kernconf.5 [new file with mode: 0644]

index 0af3a21..4b83bab 100644 (file)
@@ -1,6 +1,6 @@
 #      @(#)Makefile    8.1 (Berkeley) 6/5/93
 #      $FreeBSD: src/share/man/man5/Makefile,v 1.27.2.12 2003/05/23 22:20:24 dwhite Exp $
-#      $DragonFly: src/share/man/man5/Makefile,v 1.12 2007/05/12 07:21:51 swildner Exp $
+#      $DragonFly: src/share/man/man5/Makefile,v 1.13 2007/09/13 20:02:52 swildner Exp $
 
 #MISSING: dump.5 plot.5
 MAN=   acct.5 \
@@ -26,6 +26,7 @@ MAN=  acct.5 \
        hosts.equiv.5 \
        hosts.lpd.5 \
        intro.5 \
+       kernconf.5 \
        kernel.conf.5 \
        link.5 \
        linprocfs.5 \
diff --git a/share/man/man5/kernconf.5 b/share/man/man5/kernconf.5
new file mode 100644 (file)
index 0000000..524b8e1
--- /dev/null
@@ -0,0 +1,164 @@
+.\"
+.\" Copyright (c) 2007
+.\"    The DragonFly Project.  All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\" 3. Neither the name of The DragonFly Project nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific, prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
+.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+.\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
+.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
+.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $DragonFly: src/share/man/man5/kernconf.5,v 1.1 2007/09/13 20:02:52 swildner Exp $
+.\"
+.Dd September 13, 2007
+.Os
+.Dt KERNCONF 5
+.Sh NAME
+.Nm kernconf
+.Nd kernel configuration file
+.Sh SYNOPSIS
+.Cd cpu ...
+.Cd device ...
+.Cd ident ...
+.Cd machine ...
+.Cd machine-arch ...
+.Cd makeoptions ...
+.Cd maxusers ...
+.Cd options ...
+.Cd platform ...
+.Cd pseudo-device ...
+.Sh DESCRIPTION
+This manual page describes the structure of the kernel configuration file.
+Blank lines are ignored.
+The
+.Sq #
+character is interpreted as a comment and is ignored along with everything
+that follows it on the same line.
+See
+.Xr config 8
+for information on how to configure and build kernels.
+.Sh KEYWORDS
+The following keywords are recognized in a configuration file:
+.Bl -ohang
+.It Sy cpu Xo
+.Ar name
+.Xc
+This system is to run on the CPU type
+.Ar name .
+Legal types are
+.Sy I386_CPU
+(i386),
+.Sy I486_CPU
+(i486),
+.Sy I586_CPU
+.Tn ( Pentium ) ,
+and
+.Sy I686_CPU
+.Tn ( Pentium Pro ) .
+More than one CPU type specification can appear in a configuration file.
+.It Sy device Xo
+.Ar name
+.Xc
+Configures support for device
+.Ar name .
+.It Sy ident Xo
+.Ar string
+.Xc
+Sets the kernel identification string to
+.Ar string .
+.It Sy machine Xo
+.Ar name
+.Xc
+The system is to run on the machine type
+.Ar name .
+This is a legacy keyword and must be set to
+.Sy i386 .
+.It Sy machine_arch Xo
+.Ar name
+.Xc
+The system is to run on the machine architecture
+.Ar name .
+The only legal architecture is
+.Sy i386 .
+.It Sy makeoptions Xo
+.Ar name=value
+.Xc
+Defines a
+.Xr make 1
+macro
+.Ar name
+with the value
+.Ar value
+in the kernel Makefile.
+.It Sy maxusers Xo
+.Ar integer
+.Xc
+Set the
+.Va maxusers
+variable in the kernel.
+.It Sy options Xo
+.Ar name Ns Bq Ar =value
+.Xc
+Sets the option
+.Ar name .
+Some options expect to be assigned a value, which may be an integer,
+a double-quoted word, a bare word, or an empty string
+.Pq Qq .
+Note that those are eventually handled by the C compiler, so the rules
+of that language apply.
+.\"For more information see the
+.\".Sx OPTIONS
+.\"section.
+.It Sy platform Xo
+.Ar name
+.Xc
+Sets the platform of this kernel to
+.Ar name .
+Legal platforms are
+.Sy pc32
+and
+.Sy vkernel,
+meaning either a 32 bit
+.Tn Intel
+architecture or a virtual kernel.
+.It Sy pseudo-device Xo
+.Ar name
+.Op Ar N
+.Xc
+Includes support for the pseudo-device
+.Ar name .
+Some pseudo-devices can have multiple or
+.Ar N
+instances.
+.El
+.\".Sh OPTIONS
+.Sh SEE ALSO
+.Xr build 7 ,
+.Xr vkernel 7 ,
+.Xr config 8
+.Sh HISTORY
+The
+.Nm
+manual page first appeared in
+.Dx 1.11 .