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. 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 .\"
  30 .Dd April 9, 2021
  31 .Dt CONFIG 8
  32 .Os
  33 .Sh NAME
  34 .Nm config
  35 .Nd build system configuration files
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl CVgp
  39 .Op Fl I Ar path
  40 .Op Fl d Ar destdir
  41 .Op Fl s Ar srcdir
  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 "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.
  79 This option may be specified more than once.
  80 .It Fl d Ar destdir
  81 Use
  82 .Ar destdir
  83 as the output directory, instead of the default one.
  84 Note that
  85 .Nm
  86 does not append
  87 .Ar SYSTEM_NAME
  88 to the directory given.
  89 .It Fl s Ar srcdir
  90 Use
  91 .Ar srcdir
  92 as the source directory, instead of the default one.
  93 .It Fl m
  94 Print the MACHINE and MACHINE_ARCH values for this
  95 kernel and exit.
  96 .It Fl g
  97 Configure a system for debugging.
  98 .It Fl x Ar kernel
  99 Print kernel configuration file embedded into a kernel
 100 file.
 101 This option makes sense only if
 102 .Cd "options INCLUDE_CONFIG_FILE"
 103 entry was present in your configuration file.
 104 .It Ar SYSTEM_NAME
 105 Specify the name of the system configuration file
 106 containing device specifications, configuration options
 107 and other system parameters for one system configuration.
 108 .El
 109 .Pp
 110 The
 111 .Nm
 112 utility should be run from the
 113 .Pa conf
 114 subdirectory of the system source (usually
 115 .Pa /sys/ Ns Va ARCH Ns Pa /conf ) ,
 116 where
 117 .Va ARCH
 118 represents one of the architectures supported by
 119 .Fx .
 120 The
 121 .Nm
 122 utility creates the directory
 123 .Pa ../compile/ Ns Ar SYSTEM_NAME
 124 or the one given with the
 125 .Fl d
 126 option
 127 as necessary and places all output files there.
 128 The output of
 129 .Nm
 130 consists of a number of files; for the
 131 .Tn i386 ,
 132 they are:
 133 .Pa Makefile ,
 134 used by
 135 .Xr make 1
 136 in building the system;
 137 header files,
 138 definitions of
 139 the number of various devices that will be compiled into the system.
 140 .Pp
 141 The
 142 .Nm
 143 utility looks for kernel sources in the directory
 144 .Pa ../..
 145 or the one given with the
 146 .Fl s
 147 option.
 148 .Pp
 149 After running
 150 .Nm ,
 151 it is necessary to run
 152 .Dq Li make depend
 153 in the directory where the new makefile
 154 was created.
 155 The
 156 .Nm
 157 utility prints a reminder of this when it completes.
 158 .Pp
 159 If any other error messages are produced by
 160 .Nm ,
 161 the problems in the configuration file should be corrected and
 162 .Nm
 163 should be run again.
 164 Attempts to compile a system that had configuration errors
 165 are likely to fail.
 166 .Sh DEBUG KERNELS
 167 Traditional
 168 .Bx
 169 kernels are compiled without symbols due to the heavy load on the
 170 system when compiling a
 171 .Dq debug
 172 kernel.
 173 A debug kernel contains complete symbols for all the source files, and
 174 enables an experienced kernel programmer to analyse the cause of a problem.
 175 The
 176 debuggers available prior to
 177 .Bx 4.4 Lite
 178 were able to find some information
 179 from a normal kernel;
 180 .Xr gdb 1 Pq Pa ports/devel/gdb
 181 provides very little support for normal kernels, and a debug kernel is needed
 182 for any meaningful analysis.
 183 .Pp
 184 For reasons of history, time and space, building a debug kernel is not the
 185 default with
 186 .Fx :
 187 a debug kernel takes up to 30% longer to build and
 188 requires about 30 MB of disk storage in the build directory, compared to about 6
 189 MB for a non-debug kernel.
 190 A debug kernel is about 11 MB in size, compared to
 191 about 2 MB for a non-debug kernel.
 192 This space is used both in the root file
 193 system and at run time in memory.
 194 Use the
 195 .Fl g
 196 option to build a debug kernel.
 197 With this option,
 198 .Nm
 199 causes two kernel files to be built in the kernel build directory:
 200 .Bl -bullet
 201 .It
 202 .Pa kernel.debug
 203 is the complete debug kernel.
 204 .It
 205 .Pa kernel
 206 is a copy of the kernel with the debug symbols stripped off.
 207 This is equivalent
 208 to the normal non-debug kernel.
 209 .El
 210 .Pp
 211 There is currently little sense in installing and booting from a debug kernel,
 212 since the only tools available which use the symbols do not run on-line.
 213 There
 214 are therefore two options for installing a debug kernel:
 215 .Bl -bullet
 216 .It
 217 .Dq Li "make install"
 218 installs
 219 .Pa kernel
 220 in the root file system.
 221 .It
 222 .Dq Li "make install.debug"
 223 installs
 224 .Pa kernel.debug
 225 in the root file system.
 226 .El
 227 .Sh FILES
 228 .Bl -tag -width "/sys/ARCH/compile/SYSTEM_NAME" -compact
 229 .It Pa /sys/conf/files
 230 list of common files system is built from
 231 .It Pa /sys/conf/Makefile . Ns Va ARCH
 232 generic makefile for the
 233 .Va ARCH
 234 .It Pa /sys/conf/files . Ns Va ARCH
 235 list of
 236 .Va ARCH
 237 specific files
 238 .It Pa /sys/ Ns Va ARCH Ns Pa /compile/ Ns Ar SYSTEM_NAME
 239 default kernel build directory for system
 240 .Ar SYSTEM_NAME
 241 on
 242 .Va ARCH .
 243 .El
 244 .Sh SEE ALSO
 245 .Xr config 5
 246 .Pp
 247 The
 248 .Sx SYNOPSIS
 249 portion of each device in section 4.
 250 .Rs
 251 .\" 4.4BSD SMM:2
 252 .%A S. J. Leffler
 253 .%A M. J. Karels
 254 .%T "Building 4.3 BSD UNIX System with Config"
 255 .%B 4.4BSD System Manager's Manual (SMM)
 256 .Re
 257 .Sh HISTORY
 258 The
 259 .Nm
 260 utility appeared in
 261 .Bx 4.1 .
 262 .Pp
 263 Before support for
 264 .Fl x
 265 was introduced,
 266 .Cd "options INCLUDE_CONFIG_FILE"
 267 included entire configuration file that used to be embedded in
 268 the new kernel.
 269 This meant that
 270 .Xr strings 1
 271 could be used to extract it from a kernel:
 272 to extract the configuration information, you had to use
 273 the command:
 274 .Pp
 275 .Dl "strings -n 3 kernel | sed -n 's/^___//p'"
 276 .Sh BUGS
 277 The line numbers reported in error messages are usually off by one.