Date: Fri, 4 Jul 2003 01:45:40 -0700 (PDT) From: jkoshy@FreeBSD.ORG (Joseph Koshy) To: freebsd-doc@freebsd.org Cc: freebsd-current@freebsd.org Subject: [review request] New config.5 manual page Message-ID: <20030704084540.104CA37B401@hub.freebsd.org>
next in thread | raw e-mail | index | archive | help
This is a multipart MIME message. --==_Exmh_10592551940 Content-Type: text/plain The attached manual page documents the syntax for the kernel configuration files as understood by the config(8) program in 5-CURRENT. This syntax has diverged from the syntax understood by the original 4.4BSD config(8) program, and it is perhaps time for a new manual page. This manual entry is to be added to section 5 (file formats) of the FreeBSD manual. Could you please review and send in your comments? ---- Joseph Koshy <jkoshy@freebsd.org> Developer, The FreeBSD Project http://people.freebsd.org/~jkoshy/ --==_Exmh_10592551940 Content-Type: text/plain ; name="config.5" Content-Description: config.5 Content-Disposition: attachment; filename="config.5" .\" Copyright (c) 2003 Joseph Koshy .\" .\" 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. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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. .\" .\" $FreeBSD: src/share/man/man5/quota.user.5,v 1.3 2002/12/12 17:25:57 ru Exp $ .\" .Dd June 03, 2003 .Dt CONFIG 5 .Os .Sh NAME .Nm config .Nd kernel configuration file format .Sh DESCRIPTION A kernel configuration file specifies the configuration of a .Fx kernel. It is processed by .Xr config 8 to create a build environment where a kernel may be built using .Xr make 1 . .Sh LEXICAL STRUCTURE A kernel configuration file comprises a sequence of specification directives. .Pp A specification directive starts with a keyword at the beginning of the line and is followed by additional parameters. .Pp A specification directive may be terminated by a semicolon .Ql \&; or by a newline. Long input lines may be broken into shorter lines by starting the second and subsequent lines with a white space character. .Pp Case is significant, .Ql machine and .Ql MACHINE are different tokens. .Pp A double quote character .Ql \&\*q starts a quoted string. All characters up to the next quote character form the value of the quoted string. A .Ql \&\*q character may be inserted into a quoted string by using the sequence .Ql \e\*q . .Pp Number are specified using .Li C Ns No -style syntax. .Pp A .Ql # character starts a comment; all characters from the .Ql # character till end of line are ignored. .Pp Whitespace between tokens is ignored, except inside quoted strings. Whitespace following a comment line is ignored. .Sh CONFIGURATION DIRECTIVES Kernel configuration directives may appear in any order in a kernel configuration file. Directives are processed in order of appearance with subsequent directive lines overriding the effect of prior ones. .Pp The list of keywords and their meanings are as follows: .Bl -tag -width "makeoptions" .\" -------- CPU -------- .It Cm cpu Ar cputype Specify the CPU this kernel will run on. There can be more than one .Li cpu directives in a configuration file. The allowed list of cpu names is architecture specific and is defined in the file .Pa "sys/conf/options." Ns Ar arch . .\" -------- DEVICE -------- .It Cm device Ar name Op count Configures device .Ar name for inclusion into the kernel image. If .Ar count is specified, the device is configured for .Ar count instances. The list of valid device names is architecture specific and are defined in the files .Pa "sys/conf/files" and .Pa "sys/conf/files." Ns Ar arch . .\" -------- ENV -------- .It Cm env Ar filename Specifies a filename containing a kernel environment definition. The kernel normally uses an environment prepared for it at boot time by .Xr loader 8 . This directive makes the kernel ignore the boot environment and use the compiled in environment instead. .Pp This directive is useful for setting kernel tunables in embedded environments that do not start from .Xr loader 8 . .\" -------- HINTS -------- .It Cm hints Ar filename Specifies a file to load a static device configuration specification from. From .Fx 5.0 onwards, the kernel picks up the device configuration at boot time (see .Xr device.hints 5 Ns ). This directive configures the kernel to use the static device configuration listed in .Ar filename. .Ar filename must conform to .Xr device.hints 5 syntax. .\" -------- IDENT -------- .It Cm ident Ar name Set the kernel name to .Ar name . At least one .Cm ident directive is required. .\" -------- INCLUDE -------- .It Cm include Ar filename Read subsequent text from file .Ar filename and return to the current file after .Ar filename is successfully processed. .\" -------- MACHINE -------- .It Cm machine Ar arch Specifies the architecture of the machine the kernel is being compiled for. Legal values for .Ar arch include: .Bl -hang -compact .It alpha The DEC Alpha architecture. .It amd64 The AMD x86-64 architecture. .It i386 The IBM PC architecture. .It ia64 The Intel IA64 architecture. .It pc98 The pc96 architecture. .It powerpc The IBM PowerPC architecture. .It sparc64 The Sparc64 architecture. .El .Pp At least one machine architecture must be specified. .\" -------- MAKEOPTION -------- .It Cm makeoptions Ar options Add .Ar options to the generated makefile. .Pp .Ar options is a comma separated list of one or more option specifications. Each option specification has the form .D1 Ar MakeVariableName Op = Ar Value and results in the appropriate .Xr make 1 variable definition being inserted into the generated makefile. If only the name of the .Xr make 1 variable is specified, .Ar value is assumed to be the empty string. .Pp Example: .Bd -unfilled -offset indent -compact .Li makeoptions MYOPTION = \*qfoobar\*q .Li makeoptions MYNULLOPTION .Ed .\" -------- MAXUSERS -------- .It Cm maxusers Ar number This optional directive is used to configure the size of some kernel data structures. .Ar number should be an integer between 2 and 512, or can be 0. From .Fx 4.5 onwards, the kernel will automatically size its tables according to the available physical memory if .Cm maxusers is not specified or is specified to be 0. As explained in .Xr tuning 7 , this tunable can also be set on a running kernel using .Xr sysctl 8 . .\" -------- NOMAKEOPTION -------- .It Cm nomakeoption Ar name Removes previously defined .Xr make 1 option .Ar name from the kernel build. .\" -------- NOOPTION -------- .It Cm nooption Ar kerneloptionname Remove kernel option .Ar kerneloptionname from the list of previously defined options. .\" -------- OPTIONS -------- .It Cm options Ar optionspecs Add compile time kernel options to the kernel build. .Ar optionspecs is a comma separated list of option specifications. Each option specification has the form .D1 Ar KernelOptionName Op = Ar OptionValue If .Ar OptionValue is not specified, it is assumed to be NULL. The list of allowed options is architecture specific and are specified in the files .Pa "sys/conf/options" and .Pa "sys/conf/options." Ns Ar arch . .\" -------- PROFILE -------- .It Cm profile Ar number Enables kernel profiling if .Ar number is non-zero. If .Ar number is 2 or greater, the kernel is configured for high-resolution profiling. Kernels can also be built for profiling using the .Fl -p option to .Xr config 8 . .El .Sh OBSOLETE DIRECTIVES The following kernel configuration directives are obsolete. .Bl -tag -width "makeoptions" -compact .\" -------- CONFIG -------- .It Cm config This directive was used to specify the device to be used for the root filesystem. From .Fx 4.0 onwards, this information is passed to a booting kernel by .Xr loader 8 . .El .Sh FILES .Bl -tag -width "XXXXXXXXXXXXXXXXXXXXXXXXX" -compact .It Pa "sys/compile/" Ns Ar NAME Compile directory created from a kernel configuration. .It Pa "sys/conf/Makefile." Ns Ar arch Architecture specific .Pa Makefile fragments. .It Pa "sys/conf/files" Devices common to all architectures. .It Pa "sys/conf/files." Ns Ar arch Devices for architecture .Ar arch . .It Pa "sys/conf/options" Options common to all architectures. .It Pa "sys/conf/options." Ns Ar arch Options for architecture .Ar arch . .El .Sh SEE ALSO .Xr kenv 1 , .Xr make 1 , .Xr device.hints 5 , .Xr loader.conf 5 , .Xr config 8 , .Xr kldload 8 , .Xr loader 8 .Rs .%T "Building 4.4BSD Kernels with Config" .%A Samuel J. Leffler .%A Michael J. Karels .Re .Sh HISTORY .Xr config 8 first appeared in .Bx 4.1 , and was subsequently revised in .Bx 4.4 . The .Fx the kernel configuration mechanism changed further in .Fx 4.0 and .Fx 5.0 , moving towards an architecture supporting dynamic (boot time and runtime) kernel configuration. --==_Exmh_10592551940--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20030704084540.104CA37B401>