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