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