1.\" Copyright (c) 2003 Joseph Koshy 2.\" 3.\" Redistribution and use in source and binary forms, with or without 4.\" modification, are permitted provided that the following conditions 5.\" are met: 6.\" 1. Redistributions of source code must retain the above copyright 7.\" notice, this list of conditions and the following disclaimer. 8.\" 2. Redistributions in binary form must reproduce the above copyright 9.\" notice, this list of conditions and the following disclaimer in the 10.\" documentation and/or other materials provided with the distribution. 11.\" 12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 15.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 22.\" SUCH DAMAGE. 23.\" 24.\" $FreeBSD$ 25.\" 26.Dd July 3, 2003 27.Dt CONFIG 5 28.Os 29.Sh NAME 30.Nm config 31.Nd kernel configuration file format 32.Sh DESCRIPTION 33A kernel configuration file specifies the configuration of a 34.Fx 35kernel. 36It is processed by 37.Xr config 8 38to create a build environment where a kernel may be built using 39.Xr make 1 . 40.Ss Lexical Structure 41A kernel configuration file comprises a sequence of specification 42directives. 43.Pp 44A specification directive starts with a keyword at the beginning 45of the line and is followed by additional parameters. 46.Pp 47A specification directive may be terminated by a semicolon 48.Ql \&; 49or by a newline. 50Long input lines may be broken into shorter lines by starting the 51second and subsequent lines with a white space character. 52.Pp 53Case is significant, 54.Dq Li machine 55and 56.Dq Li MACHINE 57are different tokens. 58.Pp 59A double quote character 60.Ql \[dq] 61starts a quoted string. 62All characters up to the next quote character form the value 63of the quoted string. 64A 65.Ql \[dq] 66character may be inserted into a quoted string by 67using the sequence 68.Ql \e\[dq] . 69.Pp 70Numbers are specified using 71.Tn C Ns -style 72syntax. 73.Pp 74A 75.Ql # 76character starts a comment; all characters from the 77.Ql # 78character till the end of the current line are ignored. 79.Pp 80Whitespace between tokens is ignored, except inside quoted strings. 81Whitespace following a comment line is ignored. 82.Ss Configuration Directives 83Kernel configuration directives may appear in any order 84in a kernel configuration file. 85Directives are processed in order of appearance with subsequent 86directive lines overriding the effect of prior ones. 87.Pp 88The list of keywords and their meanings are as follows: 89.Bl -tag -width indent 90.\" -------- CPU -------- 91.It Ic cpu Ar cputype 92Specify the CPU this kernel will run on. 93There can be more than one 94.Ic cpu 95directive in a configuration file. 96The allowed list of CPU names is architecture specific and is 97defined in the file 98.Pa sys/conf/options. Ns Aq Ar arch . 99.\" -------- DEVICE -------- 100.It Ic device Ar name Op Ar count 101Configures device 102.Ar name 103for inclusion into the kernel image. 104If 105.Ar count 106is specified, the device is configured for 107.Ar count 108instances. 109Devices that are common to all architectures are 110defined in the file 111.Pa sys/conf/files . 112Devices that are specific to architecture 113.Ar arch 114are defined in the file 115.Pa sys/conf/files. Ns Aq Ar arch . 116.\" -------- ENV -------- 117.It Ic env Ar filename 118Specifies a filename containing a kernel environment definition. 119The kernel normally uses an environment prepared for it at boot time 120by 121.Xr loader 8 . 122This directive makes the kernel ignore the boot environment and use 123the compiled-in environment instead. 124.Pp 125This directive is useful for setting kernel tunables in 126embedded environments that do not start from 127.Xr loader 8 . 128.\" -------- HINTS -------- 129.It Ic hints Ar filename 130Specifies a file to load a static device configuration specification 131from. 132From 133.Fx 5.0 134onwards, the kernel reads the system's device configuration at boot 135time (see 136.Xr device.hints 5 ) . 137This directive configures the kernel to use the static device configuration 138listed in 139.Ar filename . 140The file 141.Ar filename 142must conform to the syntax specified by 143.Xr device.hints 5 . 144.\" -------- IDENT -------- 145.It Ic ident Ar name 146Set the kernel name to 147.Ar name . 148At least one 149.Ic ident 150directive is required. 151.\" -------- INCLUDE -------- 152.It Ic include Ar filename 153Read subsequent text from file 154.Ar filename 155and return to the current file after 156.Ar filename 157is successfully processed. 158.\" -------- MACHINE -------- 159.It Ic machine Ar arch 160Specifies the architecture of the machine the kernel is being 161compiled for. 162Legal values for 163.Ar arch 164include: 165.Pp 166.Bl -tag -width ".Cm powerpc" -compact 167.It Cm alpha 168The DEC Alpha architecture. 169.It Cm amd64 170The AMD x86-64 architecture. 171.It Cm i386 172The Intel x86 based PC architecture. 173.It Cm ia64 174The Intel IA64 architecture. 175.It Cm pc98 176The PC98 architecture. 177.It Cm powerpc 178The IBM PowerPC architecture. 179.It Cm sparc64 180The Sun Sparc64 architecture. 181.El 182.Pp 183A kernel configuration file may have only one 184.Ic machine 185directive. 186.\" -------- MAKEOPTION -------- 187.It Ic makeoptions Ar options 188Add 189.Ar options 190to the generated makefile. 191.Pp 192The 193.Ar options 194argument is a comma separated list of one or more option 195specifications. 196Each option specification has the form 197.Pp 198.D1 Ar MakeVariableName Ns Op = Ns Ar Value 199.Pp 200and results in the appropriate 201.Xr make 1 202variable definition being inserted into the generated makefile. 203If only the name of the 204.Xr make 1 205variable is specified, 206.Ar value 207is assumed to be the empty string. 208.Pp 209Example: 210.Bd -literal -offset indent -compact 211makeoptions MYMAKEOPTION="foobar" 212makeoptions MYNULLMAKEOPTION 213.Ed 214.\" -------- MAXUSERS -------- 215.It Ic maxusers Ar number 216This optional directive is used to configure the size 217of some kernel data structures. 218The parameter 219.Ar number 220can be 0 (the default) or an integer greater than or equal to 2. 221A value of 0 indicates that the kernel should configure 222its data structures according to the size of available 223physical memory. 224If auto configuration is requested, the kernel will set 225this tunable to a value between 32 and 384. 226.Pp 227As explained in 228.Xr tuning 7 , 229this tunable can also be set at boot time using 230.Xr loader 8 . 231.\" -------- NOMAKEOPTION -------- 232.It Ic nomakeoption Ar name 233Removes previously defined 234.Xr make 1 235option 236.Ar name 237from the kernel build. 238This directive can be used to cancel the effects of 239.Ic makeoption 240directives in files included using 241.Ic include . 242.\" -------- NOOPTION -------- 243.It Ic nooption Ar kerneloptionname 244Remove kernel option 245.Ar kerneloptionname 246from the list of previously defined options. 247This directive can be used to cancel the effects of 248.Ic options 249directives in files included using 250.Ic include . 251.\" -------- OPTIONS -------- 252.It Ic options Ar optionspecs 253Add compile time kernel options to the kernel build. 254The argument 255.Ar optionspecs 256is a comma separated list of option specifications. 257Each option specification has the form 258.Pp 259.D1 Ar KernelOptionName Ns Op = Ns Ar OptionValue 260.Pp 261If 262.Ar OptionValue 263is not specified, it is assumed to be 264.Dv NULL . 265Options common to all architectures are specified in 266the file 267.Pa sys/conf/options . 268Options specific to architecture 269.Ar arch 270are specified in the file 271.Pa sys/conf/options. Ns Aq Ar arch . 272.\" -------- PROFILE -------- 273.It Ic profile Ar number 274Enables kernel profiling if 275.Ar number 276is non-zero. 277If 278.Ar number 279is 2 or greater, the kernel is configured for 280high-resolution profiling. 281Kernels can also be built for profiling using the 282.Fl p 283option to 284.Xr config 8 . 285.El 286.Ss Obsolete Directives 287The following kernel configuration directives are obsolete. 288.Bl -tag -width indent 289.\" -------- CONFIG -------- 290.It Ic config 291This directive was used to specify the device to be used for the root 292file system. 293From 294.Fx 4.0 295onwards, this information is passed to a booting kernel by 296.Xr loader 8 . 297.El 298.Sh FILES 299.Bl -tag -width ".Pa sys/conf/Makefile. Ns Ar arch" -compact 300.It Pa sys/compile/ Ns Ar NAME 301Compile directory created from a kernel configuration. 302.It Pa sys/conf/Makefile. Ns Ar arch 303.Pa Makefile 304fragments for architecture 305.Ar arch . 306.It Pa sys/conf/files 307Devices common to all architectures. 308.It Pa sys/conf/files. Ns Ar arch 309Devices for architecture 310.Ar arch . 311.It Pa sys/conf/options 312Options common to all architectures. 313.It Pa sys/conf/options. Ns Ar arch 314Options for architecture 315.Ar arch . 316.El 317.Sh SEE ALSO 318.Xr kenv 1 , 319.Xr make 1 , 320.Xr device.hints 5 , 321.Xr loader.conf 5 , 322.Xr config 8 , 323.Xr kldload 8 , 324.Xr loader 8 325.Rs 326.%T "Building 4.4BSD Kernels with Config" 327.%A "Samuel J. Leffler" 328.%A "Michael J. Karels" 329.Re 330.Sh HISTORY 331The 332.Xr config 8 333utility first appeared in 334.Bx 4.1 , 335and was subsequently revised in 336.Bx 4.4 . 337.Pp 338The kernel configuration mechanism changed further in 339.Fx 4.0 340and 341.Fx 5.0 , 342moving toward an architecture supporting dynamic kernel 343configuration. 344