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