1. Modify config to issue different code for debugging.

2.  Config complains if you use -g:

    Debugging is enabled by default, there is no ned to specify the -g option

3.  Config warns you if you don't use -s:

    Building kernel with full debugging symbols.  Do
    "config -s BSD" for historic partial symbolic support.
    To install the debugging kernel, do make install.debug

    (BSD was the name of the config file I used; I print out the same
    name).

4.  Modify Makefile.i386, Makefile.alpha, Makefile.pc98 and config to
    work if a kernel name other than 'kernel' is specified.  This is
    not absolutely necessary, but useful, and it was relatively easy.
    I now have a kernel called /crapshit :-)

5.  Modify Makefile.i386, Makefile.alpha, Makefile.pc98 "clean" target
    to remove both the debug and normal kernel.

6.  Modify all to install the stripped kernel by default and the debug
    kernel if you enter "make install.debug".

7.  Update version number of Makefiles and config.

1 files changed, 42 insertions, 2 deletions

diff --git a/usr.sbin/config/config.8 b/usr.sbin/config/config.8
index d2be2bb..67af781 100644
--- a/usr.sbin/config/config.8
+++ b/usr.sbin/config/config.8
@@ -73,7 +73,8 @@ Available options and operands:
 .Pp
 .Bl -tag -width SYSTEM_NAME
 .It Fl g
-Configure a system for debugging.
+Configure a system for debugging.  This is the default, so this flag has no
+meaning, and causes a warning message to be printed.
 .It Fl p
 Configure a system for profiling; for example,
 .Xr kgmon 8
@@ -83,9 +84,13 @@ If two or more
 .Fl p
 options are supplied,
 .Nm
-will configure a system for high resolution profiling.
+configures a system for high resolution profiling.
 .It Fl r
 Remove the old compile directory (see below).
+.It Fl s
+Configure a system without debugging symbols.  This saves both time and space,
+but if problems occur with the kernel, it will be almost impossible to find out
+their causes.
 .It Ar SYSTEM_NAME
 Specifies the name of the system configuration file
 containing device specifications, configuration options
@@ -150,6 +155,41 @@ entire input file is embedded in the new kernel.  This means that
 can be used to extract it from a kernel. 
 .Pp
 Strings | grep ___ will print just the configure information.
+.Sh DEBUG KERNELS
+Traditional BSD kernels were compiled without symbols due to the heavy load on
+the system when compiling a 
+.if n "debug"
+.if t ``debug''
+kernel.  A debug kernel contains complete symbols for all the source files, and
+enables an experienced kernel programmer to analyse the cause of a problem.  The
+debuggers available prior to 4.4BSD-Lite were able to find some information
+from a normal kernel; this is no longer the case with
+.Xr gdb 8 ,
+and a debug kernel is needed for any meaningful analysis.
+.Pp
+Building a debug kernel is the default with FreeBSD, and the
+.Fl s
+option is required to revert to historical behaviour.  A debug kernel takes up
+to 30% longer to build and requires about 30 MB of disk storage in the build
+directory, compared to about 6 MB for a non-debug kernel.  A debug kernel is
+about 11 MB in size, compared to about 2 MB for a non-debug kernel.  This space
+is used both in the root file system and at run time in memory.  Since kernel
+storage is non-pageable, the additional space required by a debug kernel is lost
+to the system when not debugging.
+.Pp
+There is currently little sense in installing and booting from a debug kernel,
+since the only tools available which use the symbols do not run on-line.  There
+are therefore two options for installing a debug kernel:
+.Bl -bullet
+.It
+.Nm make
+.Ar install
+makes a stripped copy of the kernel and installs it in the root file system.
+.It
+.Nm make
+.Ar install.debug
+installs the complete debug kernel in the root file system.
+.El
 .Sh FILES
 .Bl -tag -width /sys/i386/conf/Makefile.i386 -compact
 .It Pa /sys/conf/files