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 March 28, 2010
  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 The
  48 .Nm
  49 utility builds a set of system configuration files from the file
  50 .Ar SYSTEM_NAME
  51 which describes
  52 the system to configure.
  53 A second file
  54 tells
  55 .Nm
  56 what files are needed to generate a system and
  57 can be augmented by configuration specific set of files
  58 that give alternate files for a specific machine
  59 (see the
  60 .Sx FILES
  61 section below).
  62 .Pp
  63 Available options and operands:
  64 .Bl -tag -width ".Ar SYSTEM_NAME"
  65 .It Fl d Ar destdir
  66 Use
  67 .Ar destdir
  68 as the output directory, instead of the default one.
  69 Note that
  70 .Nm
  71 does not append
  72 .Ar SYSTEM_NAME
  73 to the directory given.
  74 .It Fl g
  75 Configure a system for debugging.
  76 .It Fl p
  77 Configure a system for profiling; for example,
  78 .Xr kgmon 8
  79 and
  80 .Xr gprof 1 .
  81 If two or more
  82 .Fl p
  83 options are supplied,
  84 .Nm
  85 configures a system for high resolution profiling.
  86 .It Fl r
  87 Remove the old compile directory (see below).
  88 .It Ar SYSTEM_NAME
  89 Specify the name of the system configuration file
  90 containing device specifications, configuration options
  91 and other system parameters for one system configuration.
  92 .El
  93 .Pp
  94 .Nm
  95 should be run from the
  96 .Pa config
  97 subdirectory of the system source (usually
  98 .Pa /sys/config ) .
  99 .Nm
 100 creates the directory
 101 .Pa ../compile/ Ns Ar SYSTEM_NAME
 102 or the one given with the
 103 .Fl d
 104 option
 105 as necessary and places all output files there.
 106 If the output directory already exists and the
 107 .Fl r
 108 flag was specified, it will be removed first.
 109 The output of
 110 .Nm
 111 consists of a number of files; for the
 112 .Tn i386 ,
 113 they are:
 114 .Pa ioconf.c ,
 115 a description
 116 of what I/O devices are attached to the system;
 117 .Pa Makefile ,
 118 used by
 119 .Xr make 1
 120 in building the system;
 121 header files,
 122 definitions of
 123 the number of various devices that will be compiled into the system.
 124 .Pp
 125 After running
 126 .Nm ,
 127 it is necessary to run
 128 .Dq Li make depend
 129 in the directory where the new makefile
 130 was created.
 131 .Pp
 132 If any other error messages are produced by
 133 .Nm ,
 134 the problems in the configuration file should be corrected and
 135 .Nm
 136 should be run again.
 137 Attempts to compile a system that had configuration errors
 138 are likely to fail.
 139 .Pp
 140 If the
 141 .Cd "options INCLUDE_CONFIG_FILE"
 142 is used in the configuration file the
 143 entire input file is embedded in the new kernel.
 144 This means that
 145 .Xr strings 1
 146 can be used to extract it from a kernel:
 147 to extract the configuration information, use the command
 148 .Pp
 149 .Dl "strings -n 3 kernel | sed -n 's/^___//p'"
 150 .Sh DEBUG KERNELS
 151 Traditional
 152 .Bx
 153 kernels are compiled without symbols due to the heavy load on the
 154 system when compiling a
 155 .Dq debug
 156 kernel.
 157 A debug kernel contains complete symbols for all the source files, and
 158 enables an experienced kernel programmer to analyse the cause of a problem.
 159 The
 160 debuggers available prior to
 161 .Bx 4.4 Lite
 162 were able to find some information
 163 from a normal kernel;
 164 .Xr kgdb 1
 165 provides very little support for normal kernels, and a debug kernel is needed
 166 for any meaningful analysis.
 167 .Pp
 168 In order to ease posting bug reports for inexperienced users and
 169 make the debugging environment more uniform,
 170 .Dx
 171 installs kernel and modules unstripped.
 172 Debug information is not loaded into memory, so the only impact is
 173 a growth in root file-system consumption by 60MB.
 174 Those wishing to install stripped down kernel and modules can specify two new
 175 makeoptions in their kernel config file or when they run the
 176 kernel-related targets to make:
 177 .Bl -tag -width ".Va INSTALLSTRIPPEDMODULES=1"
 178 .It Va INSTALLSTRIPPED=1
 179 The installed kernel and modules will be stripped of debug info.
 180 .It Va INSTALLSTRIPPEDMODULES=1
 181 The installed modules will be stripped of debug info. The kernel will
 182 be left with debug info intact.
 183 .El
 184 .Pp
 185 Backup copies of the kernel and modules are automatically stripped of
 186 their debug information by
 187 .Xr objcopy 1 .
 188 .Sh FILES
 189 .Bl -tag -width ".It Pa /sys/platform/ Ns Va PLATFORM Ns Pa /conf/Makefile" -compact
 190 .It Pa /sys/conf/files
 191 list of common files system is built from
 192 .It Pa /sys/config/ Ns Ar SYSTEM_NAME
 193 default location for kernel configuration file
 194 .It Pa /sys/config/GENERIC
 195 default
 196 .Sy i386
 197 kernel configuration file
 198 .It Pa /sys/config/LINT
 199 kernel configuration file for checking all the sources,
 200 includes description of kernel configuration options
 201 .It Pa /sys/config/SOEKRIS
 202 kernel configuration file for the
 203 .Tn Soekris Engineering net5501
 204 board
 205 .It Pa /sys/config/VKERNEL
 206 default 32 bit
 207 .Xr vkernel 7
 208 kernel configuration file
 209 .It Pa /sys/config/VKERNEL64
 210 default 64 bit
 211 .Xr vkernel 7
 212 kernel configuration file
 213 .It Pa /sys/config/X86_64_GENERIC
 214 default
 215 .Sy x86_64
 216 kernel configuration file
 217 .It Pa /sys/compile/ Ns Ar SYSTEM_NAME
 218 default kernel build directory for system
 219 .Ar SYSTEM_NAME
 220 .It Pa /sys/platform/ Ns Va PLATFORM Ns Pa /conf/Makefile
 221 generic makefile for the
 222 .Va PLATFORM
 223 .It Pa /sys/platform/ Ns Va PLATFORM Ns Pa /conf/files
 224 list of
 225 .Va PLATFORM
 226 specific files
 227 .El
 228 .Sh SEE ALSO
 229 .Xr gprof 1 ,
 230 .Xr kgdb 1 ,
 231 .Xr make 1 ,
 232 .Xr kernconf 5 ,
 233 .Xr build 7 ,
 234 .Xr vkernel 7 ,
 235 .Xr kgmon 8
 236 .Pp
 237 The
 238 .Sx SYNOPSIS
 239 portion of each device in section 4.
 240 .Rs
 241 .%T "Building 4.3 BSD UNIX System with Config"
 242 .Re
 243 .Sh HISTORY
 244 The
 245 .Nm
 246 utility appeared in
 247 .Bx 4.1 .
 248 .Sh BUGS
 249 The line numbers reported in error messages are usually off by one.