.\"	$NetBSD: config.8,v 1.26 2003/08/07 11:25:15 agc 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. 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 26, 2003
.Dt CONFIG 8
.Os
.Sh NAME
.Nm config
.Nd build kernel compilation directories
.Sh SYNOPSIS
.Nm
.Op Fl Ppv
.Op Fl b Ar builddir
.Op Fl s Ar srcdir
.Op Ar config-file
.Nm
.Fl x
.Op Ar kernel-file
.Sh DESCRIPTION
In its first synopsis form,
.Nm
creates a kernel build directory from the machine description file
.Ar config-file ,
which describes the system to configure.
.Pp
There are several different ways to run the
.Nm
program.
The traditional way is to run
.Nm
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 vax ,
.Pa hp300 ,
and so forth), and to specify as the
.Ar config-file
the name of a machine description file located in that directory.
.Nm
will by default create files in the directory
.Pa ../compile/SYSTEMNAME ,
where
.Pa SYSTEMNAME
is the last path component of
.Ar config-file .
.Nm
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
machine description file in the build directory with the name
.Pa CONFIG ,
and run
.Nm
from within the build directory without specifying a
.Ar config-file .
.Nm
will then by default create files in the current directory.
If you run
.Nm
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 machine description file.
.Pp
Finally, you can specify the build directory for
.Nm
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 machine description file.
You must specify the location of the top-level kernel source directory if you
specify a build directory.
.Pp
If
.Ar config-file
is a binary kernel,
.Nm
will try to extract the configuration file embedded into it, which will
be present if that kernel was built either with
.Va INCLUDE_CONFIG_FILE
or
.Va INCLUDE_JUST_CONFIG
options.
This work mode requires you to manually specify a build directory with
the
.Fl b
option, which implies the need to provide a source tree too.
.Pp
If the
.Fl p
option is supplied,
.Pa .PROF
is appended to the default compilation directory name, and
.Nm
acts as if the lines
.Dq Li makeoptions PROF="-pg"
and
.Dq Li options GPROF
appeared in the machine description 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 create a separate machine description file containing the
.Li makeoptions
line.
.Pp
The
.Fl v
option causes
.Nm
to be somewhat more verbose by enabling certain warning messages.
.Pp
The
.Fl P
option causes
.Nm
to pack locators, conserving some kernel memory.
.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
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 ,
it is wise to run
.Dq Li make depend
in the directory where the new makefile
was created.
.Nm
prints a reminder of this when it completes.
.Pp
If
.Nm
stops due to errors, the problems reported should be corrected and
.Nm
should be run again.
.Nm
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.
.Pp
In its second synopsis form,
.Nm
takes the binary kernel
.Ar kernel-file
as its single argument (aside from the mandatory
.Fl x
flag), then extracts the embedded configuration file (if any) and
writes it to standard output.
If
.Ar kernel-file
is not given,
.Pa /netbsd
is used.
Configuration data will be available if the given kernel was compiled
with either
.Va INCLUDE_CONFIG_FILE
or
.Va INCLUDE_JUST_CONFIG
options.
.Sh SEE ALSO
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
.sp
.Xr options 4 ,
.Xr config 9
.Sh HISTORY
The
.Nm
command appeared in
.Bx 4.1 .
It was completely revised in
.Bx 4.4 .
The
.Fl x
option appeared in
.Nx 2.0 .