path: root/usr.sbin/config/config.8

.\"	$OpenBSD: config.8,v 1.10 1999/07/22 19:24:52 deraadt Exp $
.\"	$NetBSD: config.8,v 1.10 1996/08/31 20:58:16 mycroft Exp $
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\"     from: @(#)config.8	8.2 (Berkeley) 4/19/94
.\"
.Dd April 19, 1994
.Dt CONFIG 8
.Os
.Sh NAME
.Nm config
.Nd build kernel compilation directories
.Sh SYNOPSIS
.Nm config
.Op Fl b Ar builddir
.Op Fl s Ar srcdir
.Op Fl p
.Op Ar config-file
.Sh DESCRIPTION
.Nm config
creates a kernel build directory from the file
.Ar config-file ,
which describes the system to configure.
.Pp
There are several different ways to run the
.Nm config
program.  The traditional way is to run
.Nm config
from the
.Pa conf
subdirectory of the machine-specific directory of the system source
(usually
.Pa /sys/arch/MACHINE/conf ,
where
.Pa MACHINE
is one of
.Pa i386 ,
.Pa sparc ,
.Pa hp300 ,
and so forth), and to specify as the
.Ar config-file
the name of a file located in that directory.
.Nm config
will by default create files in the directory
.Pa ../compile/SYSTEMNAME ,
where
.Pa SYSTEMNAME
is the last path component of
.Ar config-file .
.Nm config
will assume that the top-level kernel source directory is located four
directories above the build directory.
.Pp
Another way is to create the build directory yourself, place the
configuration file in the build directory with the name
.Pa CONFIG ,
and run
.Nm config
from within the build directory without specifying a
.Ar config-file .
.Nm config
will then by default create files in the current directory.  If you
run
.Nm config
this way, you must specify the location of the top-level kernel source
directory using the
.Fl s
option or by using the
.Dq Li source
directive at the beginning of the system configuration file.
.Pp
Finally, you can specify the build directory for
.Nm config
and run it from anywhere.  You can specify a build directory with the
.Fl b
option or by using the
.Dq Li build
directive at the beginning of the system configuration file.  You must
specify the location of the top-level kernel source directory if you
specify a build directory.
.Pp
If the
.Fl p
option is supplied,
.Pa .PROF
is appended to the default compilation directory name, and
.Nm config
acts as if the lines
.Dq Li makeoptions PROF="-pg"
and
.Dq Li options GPROF
appeared in the configuration file.
This will build a system that includes profiling code; see
.Xr kgmon 8
and
.Xr gprof 1 .
The
.Fl p
flag is expected to be used for
.Dq one-shot
profiles of existing systems;
for regular profiling,
it is probably wiser to make a separate configuration
containing the
.Li makeoptions
line.
.Pp
The old undocumented
.Fl g
flag is no longer supported.
Instead, use
.Dq Li makeoptions DEBUG="-g"
and (typically)
.Dq Li options KGDB .
.Pp
The output of
.Nm config
consists of a number of files, principally
.Pa ioconf.c ,
a description of I/O devices that may be attached to the system; and a
.Pa Makefile ,
used by
.Xr make 1
in building the kernel.
.Pp
After running
.Nm config ,
it is wise to run
.Dq Li make depend
in the directory where the new makefile
was created.
.Nm config
prints a reminder of this when it completes.
.Pp
If
.Nm config
stops due to errors, the problems reported should be corrected and
.Nm config
should be run again.
.Nm config
attempts to avoid changing the compilation directory
if there are configuration errors,
but this code is not well-tested,
and some problems (such as running out of disk space)
are unrecoverable.
.Sh EXAMPLE
A custom kernel is built in the following way.
.Pp
To compile your own kernel from a non-writeable media (such as a CDROM)
mounted on
.Pa /usr/src ,
do the following:
.Sm off
.Bd -literal -offset indent
.Li #\  Xo
.Ic cd\ /
.Ar somedir
.Xc
.Li #\  Xo
.Ic cp\ /usr/src/sys/arch/
.Ar somearch
.Ic /conf/
.Ar SOMEFILE
.Ic \ .
.Xc
.Li #\  Xo
.Ic vi\ \&
.Ar SOMEFILE
.No \ \ \ (to\ make\ any\ changes)
.Xc
.Li #\  Xo
.Ic config\ -s\ /usr/src/sys\ -b\ .\ \&
.Ar SOMEFILE
.Xc
.Li #\  Xo
.Ic make
.Xc
.Ed
.Sm on
.Pp
To compile a kernel inside a writable source tree, do the following:
.Sm off
.Bd -literal -offset indent
.Li #\  Xo
.Ic cd\ /usr/src/sys/arch/
.Ar somearch
.Ic /conf
.Xc
.Li #\  Xo
.Ic vi\ \&
.Ar SOMEFILE
.No \ \ \ (to\ make\ any\ changes)
.Xc
.Li #\  Xo
.Ic config\ \&
.Ar SOMEFILE
.Xc
.Li #\  Xo
.Ic cd\ ../compile/
.Ar SOMEFILE
.Xc
.Li #\  Xo
.Ic make
.Xc
.Ed
.Sm on
.Pp
where
.Ar somedir
is a writable directory,
.Ar somearch
is the architecture (e.g.
.Ic i386 ) ,
and
.Ar SOMEFILE
should be a name indicative of a particular configuration (often
that of the hostname).
.Nm config
will warn you if a
.Ar "make clean"
is required; 
you can also do a
.Ic make depend
so that you will have dependencies there the next time you do a compile.
.Pp
After either of these two methods, you can place the new kernel (called
.Pa bsd )
in
.Pa /
(i.e.
.Pa /bsd )
and the system will boot it next time.
Most people save their backup kernels as
.Pa /bsd.1 ,
.Pa /bsd.2 ,
etc.
.Sh SEE ALSO
.Xr options 4
.Pp
The SYNOPSIS portion of each device in section 4.
.Rs
.%T "Building 4.4 BSD Systems with Config"
.\" .%T "Device Support in 4.4BSD"
.Re
.Pp
.Sh HISTORY
The
.Nm config
command appeared in
.Bx 4.1 .
It was completely revised in
.Bx 4.4 .