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