1.\" $NetBSD: config.1,v 1.15 2014/05/05 20:52:45 wiz Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" from: @(#)config.8 8.2 (Berkeley) 4/19/94 31.\" 32.Dd May 5, 2014 33.Dt CONFIG 1 34.Os 35.Sh NAME 36.Nm config 37.Nd build kernel compilation directories 38.Sh SYNOPSIS 39.Nm 40.Op Fl Ppv 41.Op Fl b Ar builddir 42.Op Fl D Ar var=value 43.Op Fl s Ar srcdir 44.Op Fl U Ar value 45.Op Ar config-file 46.Nm 47.Fl x 48.Op Ar kernel-file 49.Nm 50.Fl L 51.Op Fl v 52.Op Fl s Ar srcdir 53.Op Ar config-file 54.Sh DESCRIPTION 55In its first synopsis form, 56.Nm 57creates a kernel build directory from the machine description file 58.Ar config-file , 59which describes the system to configure. 60Refer to section 61.Sx KERNEL BUILD CONFIGURATION 62for the details of that use 63of 64.Nm . 65.Pp 66In its second synopsis form, 67.Nm 68takes the binary kernel 69.Ar kernel-file 70as its single argument (aside from the mandatory 71.Fl x 72flag), then extracts the embedded configuration file (if any) and 73writes it to standard output. 74If 75.Ar kernel-file 76is not given, and the system is not running 77.Nx 78an error is printed. 79On systems running 80.Nx 81the booted kernel is looked up using the 82.Xr sysctl 3 83variable 84.Dv machdep.booted_kernel 85and if that is not found, 86.Dv _PATH_UNIX 87.Pq Pa /netbsd 88is used. 89Configuration data will be available if the given kernel was compiled 90with either 91.Va INCLUDE_CONFIG_FILE 92or 93.Va INCLUDE_JUST_CONFIG 94options. 95.Pp 96In its third synopsis form, 97.Nm 98is a tool for the kernel developer and generates a 99.Dq lint 100configuration file to be used during regression testing. 101Refer to section 102.Sx LINT CONFIGURATION 103for the details of that use of 104.Nm . 105.Pp 106.Nm 107accepts the following parameters: 108.Bl -tag -width indent 109.It Fl b Ar builddir 110Use 111.Ar builddir 112as the kernel build directory, instead of computing and creating one 113automatically. 114.It Fl D Ar var=value 115Define a makeoptions variable to the given value. 116This is equivalent to appending a 117.Li makeoptions var=value 118line to the config file. 119.It Fl L 120Generate a lint configuration. 121See section 122.Sx LINT CONFIGURATION 123for details. 124.It Fl P 125Pack locators to save space in the resulting kernel binary. 126The amount of space saved that way is so small that this option should 127be considered historical, and of no actual use. 128.It Fl p 129Generate a build directory suited for kernel profiling. 130However, this options should be avoided in favor of the relevant options 131inside the configuration file as described in section 132.Sx KERNEL BUILD CONFIGURATION . 133.It Fl s Ar srcdir 134Point to the top of the kernel source tree. 135It must be an absolute path when 136.Nm 137is used to prepare a kernel build directory, but can be relative 138when it is used in combination with the 139.Fl L 140flag. 141.It Fl U Ar var 142Undefine the makeoption 143.Ar var . 144This is equivalent to appending the line 145.Li no makeoptions var 146to the config file. 147.It Fl v 148Increase verbosity by enabling some more warnings. 149.It Fl x 150Extract the configuration embedded in a kernel binary. 151.El 152.Ss KERNEL BUILD CONFIGURATION 153There are several different ways to run the 154.Nm 155program. 156The traditional way is to run 157.Nm 158from the 159.Pa conf 160subdirectory of the machine-specific directory of the system source 161(usually 162.Pa /sys/arch/MACHINE/conf , 163where 164.Pa MACHINE 165is one of 166.Pa vax , 167.Pa hp300 , 168and so forth), and to specify as the 169.Ar config-file 170the name of a machine description file located in that directory. 171.Nm 172will by default create files in the directory 173.Pa ../compile/SYSTEMNAME , 174where 175.Pa SYSTEMNAME 176is the last path component of 177.Ar config-file . 178.Nm 179will assume that the top-level kernel source directory is located four 180directories above the build directory. 181.Pp 182Another way is to create the build directory yourself, place the 183machine description file in the build directory with the name 184.Pa CONFIG , 185and run 186.Nm 187from within the build directory without specifying a 188.Ar config-file . 189.Nm 190will then by default create files in the current directory. 191If you run 192.Nm 193this way, you must specify the location of the top-level kernel source 194directory using the 195.Fl s 196option or by using the 197.Dq Li source 198directive at the beginning of the machine description file. 199.Pp 200Finally, you can specify the build directory for 201.Nm 202and run it from anywhere. 203You can specify a build directory with the 204.Fl b 205option or by using the 206.Dq Li build 207directive at the beginning of the machine description file. 208You must specify the location of the top-level kernel source directory if you 209specify a build directory. 210.Pp 211If 212.Ar config-file 213is a binary kernel, 214.Nm 215will try to extract the configuration file embedded into it, which will 216be present if that kernel was built either with 217.Va INCLUDE_CONFIG_FILE 218or 219.Va INCLUDE_JUST_CONFIG 220options. 221This work mode requires you to manually specify a build directory with 222the 223.Fl b 224option, which implies the need to provide a source tree too. 225.Pp 226If the 227.Fl p 228option is supplied, 229.Pa .PROF 230is appended to the default compilation directory name, and 231.Nm 232acts as if the lines 233.Dq Li makeoptions PROF="-pg" 234and 235.Dq Li options GPROF 236appeared in the machine description file. 237This will build a system that includes profiling code; see 238.Xr kgmon 8 239and 240.Xr gprof 1 . 241The 242.Fl p 243flag is expected to be used for 244.Dq one-shot 245profiles of existing systems; for regular profiling, it is probably 246wiser to create a separate machine description file containing the 247.Li makeoptions 248line. 249.Pp 250The old undocumented 251.Fl g 252flag is no longer supported. 253Instead, use 254.Dq Li makeoptions DEBUG="-g" 255and (typically) 256.Dq Li options KGDB . 257.Pp 258The output of 259.Nm 260consists of a number of files, principally 261.Pa ioconf.c , 262a description of I/O devices that may be attached to the system; and a 263.Pa Makefile , 264used by 265.Xr make 1 266in building the kernel. 267.Pp 268After running 269.Nm , 270it is wise to run 271.Dq Li make depend 272in the directory where the new makefile 273was created. 274.Nm 275prints a reminder of this when it completes. 276.Pp 277If 278.Nm 279stops due to errors, the problems reported should be corrected and 280.Nm 281should be run again. 282.Nm 283attempts to avoid changing the compilation directory 284if there are configuration errors, 285but this code is not well-tested, 286and some problems (such as running out of disk space) 287are unrecoverable. 288.Ss LINT CONFIGURATION 289A so-called 290.Dq lint 291configuration should include everything from the kernel that can 292possibly be selected. 293The rationale is to provide a way to reach all the code a user might 294select, in order to make sure all options and drivers compile without 295error for a given source tree. 296.Pp 297When used with the 298.Fl L 299flag, 300.Nm 301takes the regular configuration file 302.Ar config-file 303and prints on the standard output a configuration file that includes 304.Ar config-file , 305selects all options and file-systems the user can possibly select, 306and defines an instance of every possible attachment as described by 307the kernel option definition files used by 308.Ar config-file . 309.Pp 310The resulting configuration file is meant as a way to select all 311possible features in order to test that each of them compiles. 312It is not meant to result in a kernel binary that can run on any 313hardware. 314.Pp 315Unlike the first synopsis form, the provided 316.Ar srcdir 317is relative to the current working directory. 318In the first synopsis form, it is relative to the build directory. 319.Sh SEE ALSO 320The SYNOPSIS portion of each device in section 4. 321.\".Rs 322.\" .%T "Building 4.4 BSD Systems with Config" 323.\" .%T "Device Support in 4.4BSD" 324.\".Re 325.Pp 326.Xr options 4 , 327.Xr config 5 , 328.Xr config 9 329.Sh HISTORY 330The 331.Nm 332command appeared in 333.Bx 4.1 . 334It was completely revised in 335.Bx 4.4 . 336The 337.Fl x 338option appeared in 339.Nx 2.0 . 340The 341.Fl L 342option appeared in 343.Nx 5.0 . 344