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