1.\" $NetBSD: config.1,v 1.13 2012/08/30 12:42:41 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 August 30, 2012 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 s Ar srcdir 43.Op Ar config-file 44.Nm 45.Fl x 46.Op Ar kernel-file 47.Nm 48.Fl L 49.Op Fl v 50.Op Fl s Ar srcdir 51.Op Ar config-file 52.Sh DESCRIPTION 53In its first synopsis form, 54.Nm 55creates a kernel build directory from the machine description file 56.Ar config-file , 57which describes the system to configure. 58Refer to section 59.Sx KERNEL BUILD CONFIGURATION 60for the details of that use 61of 62.Nm . 63.Pp 64In its second synopsis form, 65.Nm 66takes the binary kernel 67.Ar kernel-file 68as its single argument (aside from the mandatory 69.Fl x 70flag), then extracts the embedded configuration file (if any) and 71writes it to standard output. 72If 73.Ar kernel-file 74is not given, and the system is not running 75.Nx 76an error is printed. 77On systems running 78.Nx 79the booted kernel is looked up using the 80.Xr sysctl 3 81variable 82.Dv machdep.booted_kernel 83and if that is not found, 84.Dv _PATH_UNIX 85.Pq Pa /netbsd 86is used. 87Configuration data will be available if the given kernel was compiled 88with either 89.Va INCLUDE_CONFIG_FILE 90or 91.Va INCLUDE_JUST_CONFIG 92options. 93.Pp 94In its third synopsis form, 95.Nm 96is a tool for the kernel developer and generates a 97.Dq lint 98configuration file to be used during regression testing. 99Refer to section 100.Sx LINT CONFIGURATION 101for the details of that use of 102.Nm . 103.Pp 104.Nm 105accepts the following parameters: 106.Bl -tag -width indent 107.It Fl b Ar builddir 108Use 109.Ar builddir 110as the kernel build directory, instead of computing and creating one 111automatically. 112.It Fl L 113Generate a lint configuration. 114See section 115.Sx LINT CONFIGURATION 116for details. 117.It Fl P 118Pack locators to save space in the resulting kernel binary. 119The amount of space saved that way is so small that this option should 120be considered historical, and of no actual use. 121.It Fl p 122Generate a build directory suited for kernel profiling. 123However, this options should be avoided in favor of the relevant options 124inside the configuration file as described in section 125.Sx KERNEL BUILD CONFIGURATION . 126.It Fl s Ar srcdir 127Point to the top of the kernel source tree. 128It must be an absolute path when 129.Nm 130is used to prepare a kernel build directory, but can be relative 131when it is used in combination with the 132.Fl L 133flag. 134.It Fl v 135Increase verbosity by enabling some more warnings. 136.It Fl x 137Extract the configuration embedded in a kernel binary. 138.El 139.Ss KERNEL BUILD CONFIGURATION 140There are several different ways to run the 141.Nm 142program. 143The traditional way is to run 144.Nm 145from the 146.Pa conf 147subdirectory of the machine-specific directory of the system source 148(usually 149.Pa /sys/arch/MACHINE/conf , 150where 151.Pa MACHINE 152is one of 153.Pa vax , 154.Pa hp300 , 155and so forth), and to specify as the 156.Ar config-file 157the name of a machine description file located in that directory. 158.Nm 159will by default create files in the directory 160.Pa ../compile/SYSTEMNAME , 161where 162.Pa SYSTEMNAME 163is the last path component of 164.Ar config-file . 165.Nm 166will assume that the top-level kernel source directory is located four 167directories above the build directory. 168.Pp 169Another way is to create the build directory yourself, place the 170machine description file in the build directory with the name 171.Pa CONFIG , 172and run 173.Nm 174from within the build directory without specifying a 175.Ar config-file . 176.Nm 177will then by default create files in the current directory. 178If you run 179.Nm 180this way, you must specify the location of the top-level kernel source 181directory using the 182.Fl s 183option or by using the 184.Dq Li source 185directive at the beginning of the machine description file. 186.Pp 187Finally, you can specify the build directory for 188.Nm 189and run it from anywhere. 190You can specify a build directory with the 191.Fl b 192option or by using the 193.Dq Li build 194directive at the beginning of the machine description file. 195You must specify the location of the top-level kernel source directory if you 196specify a build directory. 197.Pp 198If 199.Ar config-file 200is a binary kernel, 201.Nm 202will try to extract the configuration file embedded into it, which will 203be present if that kernel was built either with 204.Va INCLUDE_CONFIG_FILE 205or 206.Va INCLUDE_JUST_CONFIG 207options. 208This work mode requires you to manually specify a build directory with 209the 210.Fl b 211option, which implies the need to provide a source tree too. 212.Pp 213If the 214.Fl p 215option is supplied, 216.Pa .PROF 217is appended to the default compilation directory name, and 218.Nm 219acts as if the lines 220.Dq Li makeoptions PROF="-pg" 221and 222.Dq Li options GPROF 223appeared in the machine description file. 224This will build a system that includes profiling code; see 225.Xr kgmon 8 226and 227.Xr gprof 1 . 228The 229.Fl p 230flag is expected to be used for 231.Dq one-shot 232profiles of existing systems; for regular profiling, it is probably 233wiser to create a separate machine description file containing the 234.Li makeoptions 235line. 236.Pp 237The old undocumented 238.Fl g 239flag is no longer supported. 240Instead, use 241.Dq Li makeoptions DEBUG="-g" 242and (typically) 243.Dq Li options KGDB . 244.Pp 245The output of 246.Nm 247consists of a number of files, principally 248.Pa ioconf.c , 249a description of I/O devices that may be attached to the system; and a 250.Pa Makefile , 251used by 252.Xr make 1 253in building the kernel. 254.Pp 255After running 256.Nm , 257it is wise to run 258.Dq Li make depend 259in the directory where the new makefile 260was created. 261.Nm 262prints a reminder of this when it completes. 263.Pp 264If 265.Nm 266stops due to errors, the problems reported should be corrected and 267.Nm 268should be run again. 269.Nm 270attempts to avoid changing the compilation directory 271if there are configuration errors, 272but this code is not well-tested, 273and some problems (such as running out of disk space) 274are unrecoverable. 275.Ss LINT CONFIGURATION 276A so-called 277.Dq lint 278configuration should include everything from the kernel that can 279possibly be selected. 280The rationale is to provide a way to reach all the code a user might 281select, in order to make sure all options and drivers compile without 282error for a given source tree. 283.Pp 284When used with the 285.Fl L 286flag, 287.Nm 288takes the regular configuration file 289.Ar config-file 290and prints on the standard output a configuration file that includes 291.Ar config-file , 292selects all options and file-systems the user can possibly select, 293and defines an instance of every possible attachment as described by 294the kernel option definition files used by 295.Ar config-file . 296.Pp 297The resulting configuration file is meant as a way to select all 298possible features in order to test that each of them compiles. 299It is not meant to result in a kernel binary that can run on any 300hardware. 301.Pp 302Unlike the first synopsis form, the provided 303.Ar srcdir 304is relative to the current working directory. 305In the first synopsis form, it is relative to the build directory. 306.Sh SEE ALSO 307The SYNOPSIS portion of each device in section 4. 308.\".Rs 309.\" .%T "Building 4.4 BSD Systems with Config" 310.\" .%T "Device Support in 4.4BSD" 311.\".Re 312.Pp 313.Xr options 4 , 314.Xr config 5 , 315.Xr config 9 316.Sh HISTORY 317The 318.Nm 319command appeared in 320.Bx 4.1 . 321It was completely revised in 322.Bx 4.4 . 323The 324.Fl x 325option appeared in 326.Nx 2.0 . 327The 328.Fl L 329option appeared in 330.Nx 5.0 . 331