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: src/usr.sbin/config/config.8,v 1.21.2.7 2003/04/23 07:32:39 brueffer Exp $
  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 gpr
  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 The
  62 .Nm
  63 utility builds a set of system configuration files from the file
  64 .Ar SYSTEM_NAME
  65 which describes
  66 the system to configure.
  67 A second file
  68 tells
  69 .Nm
  70 what files are needed to generate a system and
  71 can be augmented by configuration specific set of files
  72 that give alternate files for a specific machine
  73 (see the
  74 .Sx FILES
  75 section below).
  76 .Pp
  77 Available options and operands:
  78 .Bl -tag -width ".Ar SYSTEM_NAME"
  79 .It Fl d Ar destdir
  80 Use
  81 .Ar destdir
  82 as the output directory, instead of the default one.
  83 Note that
  84 .Nm
  85 does not append
  86 .Ar SYSTEM_NAME
  87 to the directory given.
  88 .It Fl g
  89 Configure a system for debugging.
  90 .It Fl p
  91 Configure a system for profiling; for example,
  92 .Xr kgmon 8
  93 and
  94 .Xr gprof 1 .
  95 If two or more
  96 .Fl p
  97 options are supplied,
  98 .Nm
  99 configures a system for high resolution profiling.
 100 .It Fl r
 101 Remove the old compile directory (see below).
 102 .It Ar SYSTEM_NAME
 103 Specify the name of the system configuration file
 104 containing device specifications, configuration options
 105 and other system parameters for one system configuration.
 106 .El
 107 .Pp
 108 .Nm
 109 should be run from the
 110 .Pa conf
 111 subdirectory of the system source (usually
 112 .Pa /sys/ Ns Va ARCH Ns Pa /conf ) ,
 113 where
 114 .Va ARCH
 115 represents one of the architectures supported by
 116 .Fx .
 117 .Nm
 118 creates the directory
 119 .Pa ../../compile/ Ns Ar SYSTEM_NAME
 120 or the one given with the
 121 .Fl d
 122 option
 123 as necessary and places all output files there.
 124 If the output directory already exists and the
 125 .Fl r
 126 flag was specified, it will be removed first.
 127 The output of
 128 .Nm
 129 consists of a number of files; for the
 130 .Tn i386 ,
 131 they are:
 132 .Pa ioconf.c ,
 133 a description
 134 of what I/O devices are attached to the system;
 135 .Pa Makefile ,
 136 used by
 137 .Xr make 1
 138 in building the system;
 139 header files,
 140 definitions of
 141 the number of various devices that will be compiled into the system.
 142 .Pp
 143 After running
 144 .Nm ,
 145 it is necessary to run
 146 .Dq Li make depend
 147 in the directory where the new makefile
 148 was created.
 149 The
 150 .Nm
 151 utility prints a reminder of this when it completes.
 152 .Pp
 153 If any other error messages are produced by
 154 .Nm ,
 155 the problems in the configuration file should be corrected and
 156 .Nm
 157 should be run again.
 158 Attempts to compile a system that had configuration errors
 159 are likely to fail.
 160 .Pp
 161 If the
 162 .Cd "options INCLUDE_CONFIG_FILE"
 163 is used in the configuration file the
 164 entire input file is embedded in the new kernel.
 165 This means that
 166 .Xr strings 1
 167 can be used to extract it from a kernel:
 168 to extract the configuration information, use the command
 169 .Pp
 170 .Dl "strings -n 3 kernel | sed -n 's/^___//p'"
 171 .Sh DEBUG KERNELS
 172 Traditional
 173 .Bx
 174 kernels are compiled without symbols due to the heavy load on the
 175 system when compiling a
 176 .Dq debug
 177 kernel.
 178 A debug kernel contains complete symbols for all the source files, and
 179 enables an experienced kernel programmer to analyse the cause of a problem.
 180 The
 181 debuggers available prior to
 182 .Bx 4.4 Lite
 183 were able to find some information
 184 from a normal kernel;
 185 .Xr gdb 1
 186 provides very little support for normal kernels, and a debug kernel is needed
 187 for any meaningful analysis.
 188 .Pp
 189 For reasons of history, time and space, building a debug kernel is not the
 190 default with
 191 .Fx :
 192 a debug kernel takes up to 30% longer to build and
 193 requires about 30 MB of disk storage in the build directory, compared to about 6
 194 MB for a non-debug kernel.
 195 A debug kernel is about 11 MB in size, compared to
 196 about 2 MB for a non-debug kernel.
 197 This space is used both in the root file
 198 system and at run time in memory.
 199 Use the
 200 .Fl g
 201 option to build a debug kernel.
 202 With this option,
 203 .Nm
 204 causes two kernel files to be built in the kernel build directory:
 205 .Bl -bullet
 206 .It
 207 .Pa kernel.debug
 208 is the complete debug kernel.
 209 .It
 210 .Pa kernel
 211 is a copy of the kernel with the debug symbols stripped off.
 212 This is equivalent
 213 to the normal non-debug kernel.
 214 .El
 215 .Pp
 216 There is currently little sense in installing and booting from a debug kernel,
 217 since the only tools available which use the symbols do not run on-line.
 218 There
 219 are therefore two options for installing a debug kernel:
 220 .Bl -bullet
 221 .It
 222 .Dq Li "make install"
 223 installs
 224 .Pa kernel
 225 in the root file system.
 226 .It
 227 .Dq Li "make install.debug"
 228 installs
 229 .Pa kernel.debug
 230 in the root file system.
 231 .El
 232 .Sh FILES
 233 .Bl -tag -width ".Pa /sys/ Ns Va ARCH Ns Pa /conf/files. Ns Ar SYSTEM_NAME" -compact
 234 .It Pa /sys/conf/files
 235 list of common files system is built from
 236 .It Pa /sys/conf/Makefile. Ns Va ARCH
 237 generic makefile for the
 238 .Va ARCH
 239 .It Pa /sys/conf/files. Ns Va ARCH
 240 list of
 241 .Va ARCH
 242 specific files
 243 .It Pa /sys/ Ns Va ARCH Ns Pa /conf/files. Ns Ar SYSTEM_NAME
 244 list of files specific to
 245 .Ar SYSTEM_NAME
 246 on
 247 .Va ARCH
 248 .It Pa /sys/compile/ Ns Ar SYSTEM_NAME
 249 default kernel build directory for system
 250 .Ar SYSTEM_NAME .
 251 .El
 252 .Sh SEE ALSO
 253 The
 254 .Sx SYNOPSIS
 255 portion of each device in section 4.
 256 .Rs
 257 .%T "Building 4.3 BSD UNIX System with Config"
 258 .Re
 259 .Sh BUGS
 260 The line numbers reported in error messages are usually off by one.
 261 .Sh HISTORY
 262 The
 263 .Nm
 264 utility appeared in
 265 .Bx 4.1 .