xref: /freebsd/usr.sbin/config/config.8 (revision 76b28ad6ab6dc8d4a62cb7de7f143595be535813)
1.\" Copyright (c) 1980, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 4. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     @(#)config.8	8.2 (Berkeley) 4/19/94
29.\" $FreeBSD$
30.\"
31.Dd May 8, 2007
32.Dt CONFIG 8
33.Os
34.Sh NAME
35.Nm config
36.Nd build system configuration files
37.Sh SYNOPSIS
38.Nm
39.Op Fl CVgp
40.Op Fl I Ar path
41.Op Fl d Ar destdir
42.Ar SYSTEM_NAME
43.Nm
44.Op Fl x Ar kernel
45.Sh DESCRIPTION
46The
47.Nm
48utility builds a set of system configuration files from the file
49.Ar SYSTEM_NAME
50which describes
51the system to configure.
52A second file
53tells
54.Nm
55what files are needed to generate a system and
56can be augmented by configuration specific set of files
57that give alternate files for a specific machine
58(see the
59.Sx FILES
60section below).
61.Pp
62Available options and operands:
63.Bl -tag -width ".Ar SYSTEM_NAME"
64.It Fl V
65Print the
66.Nm
67version number.
68.It Fl C
69If the INCLUDE_CONFIG_FILE is present in a configuration file,
70kernel image will contain full configuration files included
71literally (preserving comments).
72This flag is kept for backward compatibility.
73.It Fl I Ar path
74Search in
75.Ar path
76for any file included by the
77.Ic include
78directive.  This option may be specified more than once.
79.It Fl d Ar destdir
80Use
81.Ar destdir
82as the output directory, instead of the default one.
83Note that
84.Nm
85does not append
86.Ar SYSTEM_NAME
87to the directory given.
88.It Fl m
89Print the MACHINE and MACHINE_ARCH values for this
90kernel and exit.
91.It Fl g
92Configure a system for debugging.
93.It Fl x Ar kernel
94Print kernel configuration file embedded into a kernel
95file.
96This option makes sense only if
97.Cd "options INCLUDE_CONFIG_FILE"
98entry was present in your configuration file.
99.It Fl p
100Configure a system for profiling; for example,
101.Xr kgmon 8
102and
103.Xr gprof 1 .
104If two or more
105.Fl p
106options are supplied,
107.Nm
108configures a system for high resolution profiling.
109.It Ar SYSTEM_NAME
110Specify the name of the system configuration file
111containing device specifications, configuration options
112and other system parameters for one system configuration.
113.El
114.Pp
115The
116.Nm
117utility should be run from the
118.Pa conf
119subdirectory of the system source (usually
120.Pa /sys/ Ns Va ARCH Ns Pa /conf ) ,
121where
122.Va ARCH
123represents one of the architectures supported by
124.Fx .
125The
126.Nm
127utility creates the directory
128.Pa ../compile/ Ns Ar SYSTEM_NAME
129or the one given with the
130.Fl d
131option
132as necessary and places all output files there.
133The output of
134.Nm
135consists of a number of files; for the
136.Tn i386 ,
137they are:
138.Pa Makefile ,
139used by
140.Xr make 1
141in building the system;
142header files,
143definitions of
144the number of various devices that will be compiled into the system.
145.Pp
146After running
147.Nm ,
148it is necessary to run
149.Dq Li make depend
150in the directory where the new makefile
151was created.
152The
153.Nm
154utility prints a reminder of this when it completes.
155.Pp
156If any other error messages are produced by
157.Nm ,
158the problems in the configuration file should be corrected and
159.Nm
160should be run again.
161Attempts to compile a system that had configuration errors
162are likely to fail.
163.Sh DEBUG KERNELS
164Traditional
165.Bx
166kernels are compiled without symbols due to the heavy load on the
167system when compiling a
168.Dq debug
169kernel.
170A debug kernel contains complete symbols for all the source files, and
171enables an experienced kernel programmer to analyse the cause of a problem.
172The
173debuggers available prior to
174.Bx 4.4 Lite
175were able to find some information
176from a normal kernel;
177.Xr gdb 1
178provides very little support for normal kernels, and a debug kernel is needed
179for any meaningful analysis.
180.Pp
181For reasons of history, time and space, building a debug kernel is not the
182default with
183.Fx :
184a debug kernel takes up to 30% longer to build and
185requires about 30 MB of disk storage in the build directory, compared to about 6
186MB for a non-debug kernel.
187A debug kernel is about 11 MB in size, compared to
188about 2 MB for a non-debug kernel.
189This space is used both in the root file
190system and at run time in memory.
191Use the
192.Fl g
193option to build a debug kernel.
194With this option,
195.Nm
196causes two kernel files to be built in the kernel build directory:
197.Bl -bullet
198.It
199.Pa kernel.debug
200is the complete debug kernel.
201.It
202.Pa kernel
203is a copy of the kernel with the debug symbols stripped off.
204This is equivalent
205to the normal non-debug kernel.
206.El
207.Pp
208There is currently little sense in installing and booting from a debug kernel,
209since the only tools available which use the symbols do not run on-line.
210There
211are therefore two options for installing a debug kernel:
212.Bl -bullet
213.It
214.Dq Li "make install"
215installs
216.Pa kernel
217in the root file system.
218.It
219.Dq Li "make install.debug"
220installs
221.Pa kernel.debug
222in the root file system.
223.El
224.Sh FILES
225.Bl -tag -width ".Pa /sys/ Ns Va ARCH Ns Pa /compile/ Ns Ar SYSTEM_NAME" -compact
226.It Pa /sys/conf/files
227list of common files system is built from
228.It Pa /sys/conf/Makefile. Ns Va ARCH
229generic makefile for the
230.Va ARCH
231.It Pa /sys/conf/files. Ns Va ARCH
232list of
233.Va ARCH
234specific files
235.It Pa /sys/ Ns Va ARCH Ns Pa /compile/ Ns Ar SYSTEM_NAME
236default kernel build directory for system
237.Ar SYSTEM_NAME
238on
239.Va ARCH .
240.El
241.Sh SEE ALSO
242.Xr config 5
243.Pp
244The
245.Sx SYNOPSIS
246portion of each device in section 4.
247.Rs
248.%T "Building 4.3 BSD UNIX System with Config"
249.Re
250.Sh HISTORY
251The
252.Nm
253utility appeared in
254.Bx 4.1 .
255.Pp
256Before support for
257.Fl x
258was introduced,
259.Cd "options INCLUDE_CONFIG_FILE"
260included entire configuration file that used to be embedded in
261the new kernel.
262This meant that
263.Xr strings 1
264could be used to extract it from a kernel:
265to extract the configuration information, you had to use
266the command:
267.Pp
268.Dl "strings -n 3 kernel | sed -n 's/^___//p'"
269.Sh BUGS
270The line numbers reported in error messages are usually off by one.
271