kernel - Bring in dff23c692 from FreeBSD

[dragonfly.git] / usr.sbin / config / config.8

.\" Copyright (c) 1980, 1991, 1993
.\"     The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)config.8    8.2 (Berkeley) 4/19/94
.\" $FreeBSD: src/usr.sbin/config/config.8,v 1.21.2.7 2003/04/23 07:32:39 brueffer Exp $
.\"
.Dd March 28, 2010
.Dt CONFIG 8
.Os
.Sh NAME
.Nm config
.Nd build system configuration files
.Sh SYNOPSIS
.Nm
.Op Fl gpr
.Op Fl d Ar destdir
.Ar SYSTEM_NAME
.Sh DESCRIPTION
The
.Nm
utility builds a set of system configuration files from the file
.Ar SYSTEM_NAME
which describes
the system to configure.
A second file
tells
.Nm
what files are needed to generate a system and
can be augmented by configuration specific set of files
that give alternate files for a specific machine
(see the
.Sx FILES
section below).
.Pp
Available options and operands:
.Bl -tag -width ".Ar SYSTEM_NAME"
.It Fl d Ar destdir
Use
.Ar destdir
as the output directory, instead of the default one.
Note that
.Nm
does not append
.Ar SYSTEM_NAME
to the directory given.
.It Fl g
Configure a system for debugging.
.It Fl p
Configure a system for profiling; for example,
.Xr kgmon 8
and
.Xr gprof 1 .
If two or more
.Fl p
options are supplied,
.Nm
configures a system for high resolution profiling.
.It Fl r
Remove the old compile directory (see below).
.It Ar SYSTEM_NAME
Specify the name of the system configuration file
containing device specifications, configuration options
and other system parameters for one system configuration.
.El
.Pp
.Nm
should be run from the
.Pa config
subdirectory of the system source (usually
.Pa /sys/config ) .
.Nm
creates the directory
.Pa ../compile/ Ns Ar SYSTEM_NAME
or the one given with the
.Fl d
option
as necessary and places all output files there.
If the output directory already exists and the
.Fl r
flag was specified, it will be removed first.
The output of
.Nm
consists of a number of files; for the
.Tn i386 ,
they are:
.Pa ioconf.c ,
a description
of what I/O devices are attached to the system;
.Pa Makefile ,
used by
.Xr make 1
in building the system;
header files,
definitions of
the number of various devices that will be compiled into the system.
.Pp
After running
.Nm ,
it is necessary to run
.Dq Li make depend
in the directory where the new makefile
was created.
.Pp
If any other error messages are produced by
.Nm ,
the problems in the configuration file should be corrected and
.Nm
should be run again.
Attempts to compile a system that had configuration errors
are likely to fail.
.Pp
If the
.Cd "options INCLUDE_CONFIG_FILE"
is used in the configuration file the
entire input file is embedded in the new kernel.
This means that
.Xr strings 1
can be used to extract it from a kernel:
to extract the configuration information, use the command
.Pp
.Dl "strings -n 3 kernel | sed -n 's/^___//p'"
.Sh DEBUG KERNELS
Traditional
.Bx
kernels are compiled without symbols due to the heavy load on the
system when compiling a
.Dq debug
kernel.
A debug kernel contains complete symbols for all the source files, and
enables an experienced kernel programmer to analyse the cause of a problem.
The
debuggers available prior to
.Bx 4.4 Lite
were able to find some information
from a normal kernel;
.Xr kgdb 1
provides very little support for normal kernels, and a debug kernel is needed
for any meaningful analysis.
.Pp
In order to ease posting bug reports for inexperienced users and
make the debugging environment more uniform,
.Dx
installs kernel and modules unstripped.
Debug information is not loaded into memory, so the only impact is
a growth in root file-system consumption by 60MB.
Those wishing to install stripped down kernel and modules can specify two new
makeoptions in their kernel config file or when they run the
kernel-related targets to make:
.Bl -tag -width ".Va INSTALLSTRIPPEDMODULES=1"
.It Va INSTALLSTRIPPED=1
The installed kernel and modules will be stripped of debug info.
.It Va INSTALLSTRIPPEDMODULES=1
The installed modules will be stripped of debug info. The kernel will
be left with debug info intact.
.El
.Pp
Backup copies of the kernel and modules are automatically stripped of
their debug information by
.Xr objcopy 1 .
.Sh FILES
.Bl -tag -width ".It Pa /sys/platform/ Ns Va PLATFORM Ns Pa /conf/Makefile" -compact
.It Pa /sys/conf/files
list of common files system is built from
.It Pa /sys/config/ Ns Ar SYSTEM_NAME
default location for kernel configuration file
.It Pa /sys/config/GENERIC
default
.Sy i386
kernel configuration file
.It Pa /sys/config/LINT
kernel configuration file for checking all the sources,
includes description of kernel configuration options
.It Pa /sys/config/SOEKRIS
kernel configuration file for the
.Tn Soekris Engineering net5501
board
.It Pa /sys/config/VKERNEL
default 32 bit
.Xr vkernel 7
kernel configuration file
.It Pa /sys/config/VKERNEL64
default 64 bit
.Xr vkernel 7
kernel configuration file
.It Pa /sys/config/X86_64_GENERIC
default
.Sy x86_64
kernel configuration file
.It Pa /sys/compile/ Ns Ar SYSTEM_NAME
default kernel build directory for system
.Ar SYSTEM_NAME
.It Pa /sys/platform/ Ns Va PLATFORM Ns Pa /conf/Makefile
generic makefile for the
.Va PLATFORM
.It Pa /sys/platform/ Ns Va PLATFORM Ns Pa /conf/files
list of
.Va PLATFORM
specific files
.El
.Sh SEE ALSO
.Xr gprof 1 ,
.Xr kgdb 1 ,
.Xr make 1 ,
.Xr kernconf 5 ,
.Xr build 7 ,
.Xr vkernel 7 ,
.Xr kgmon 8
.Pp
The
.Sx SYNOPSIS
portion of each device in section 4.
.Rs
.%T "Building 4.3 BSD UNIX System with Config"
.Re
.Sh HISTORY
The
.Nm
utility appeared in
.Bx 4.1 .
.Sh BUGS
The line numbers reported in error messages are usually off by one.