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