usr.sbin/config/config.8

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