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