From nobody@FreeBSD.ORG  Fri Aug  4 07:20:57 2000
Return-Path: <nobody@FreeBSD.ORG>
Received: by hub.freebsd.org (Postfix, from userid 32767)
	id 881E137BB54; Fri,  4 Aug 2000 07:20:57 -0700 (PDT)
Message-Id: <20000804142057.881E137BB54@hub.freebsd.org>
Date: Fri,  4 Aug 2000 07:20:57 -0700 (PDT)
From: jefblaine@mediaone.net
Sender: nobody@FreeBSD.ORG
To: freebsd-gnats-submit@FreeBSD.org
Subject: Building a kernel with debugging info section could use a rework
X-Send-Pr-Version: www-1.0

>Number:         20400
>Category:       docs
>Synopsis:       Building a kernel with debugging info section could use a rework
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    freebsd-doc
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Aug 04 07:30:01 PDT 2000
>Closed-Date:    Mon Sep 3 11:08:39 PDT 2001
>Last-Modified:  Mon Sep 03 11:09:32 PDT 2001
>Originator:     Jeff Blaine
>Release:        4.0-RELEASE
>Organization:
>Environment:
FreeBSD kickflop 4.0-RELEASE FreeBSD 4.0-RELEASE #0: Fri Jul 28 09:39:54 EDT 200
0     root@kickflop:/usr/src/sys/compile/BUNK  i386
>Description:
I was thinking that the 2.2.1 subsection of
http://www.freebsd.org/handbook/kerneldebug.html
could use a little bit of a reworking in those first 7 paragraphs
and show steps instead of just generalized information.  For
example, there are very specific steps to follow to get a kernel
built with debugging symbols in it, and that's the absolute first
step to doing any kernel debugging work from crashes and such.
One of those steps, the most important one(!), is using
'config -g KERNEL_CONFIG_FILE' and not 'config KERNEL_CONFIG_FILE'
as part of the build, regardless of the 'makeoptions DEBUG=-g' in
KERNEL_CONFIG_FILE, yet this step is casually mentioned at the end
of one of the paragraphs as 'Config your kernel using config -g'

What I have issue with is the casual (and not formal step-by-step)
nature of the first half of that subsection.  The part where it
shows how to fire up gdb -k (and from then on) is done in this
fashion, but the first half of the subsection is not.

Also, what's all this about 'kgdb' (in terminal type font as if it
is a command to type)?  If the command is 'gdb -k' nowadays, and has
been for some time, why give it this secret codeword?  Call it
'gdb in kernel debugging mode' or just 'gdb -k'...
>How-To-Repeat:

>Fix:


>Release-Note:
>Audit-Trail:

From: Sheldon Hearn <sheldonh@uunet.co.za>
To: jefblaine@mediaone.net
Cc: freebsd-gnats-submit@FreeBSD.ORG
Subject: Re: docs/20400: Building a kernel with debugging info section could use a rework 
Date: Fri, 04 Aug 2000 16:46:27 +0200

 On Fri, 04 Aug 2000 07:20:57 MST, jefblaine@mediaone.net wrote:
 
 > What I have issue with is the casual (and not formal step-by-step)
 > nature of the first half of that subsection.  The part where it
 > shows how to fire up gdb -k (and from then on) is done in this
 > fashion, but the first half of the subsection is not.
 
 While I understand that your PR docs/20398 probably requires a patch
 thta you may not feel confident about producing yourself, this looks
 like a case of someone needing to produce better text for whole
 paragraphs in toto.
 
 That's something you could probably do yourself, especially since you're
 probably the person closest to the problem right now. :-)
 
 Care to try your hand at contributing some text? :-)
 
 > Also, what's all this about 'kgdb' (in terminal type font as if it
 > is a command to type)?  If the command is 'gdb -k' nowadays, and has
 > been for some time, why give it this secret codeword?
 
 Things have changed and the documentation doesn't just "catch up" --
 someone edits it. :-)
 
 If you'd like to help, all you'll need to is to spend some time getting
 to know the SGML flavour the -doc guys use for the handbook.  It sounds
 to me like you have some valuable contributions just aching to come out.
 :-)
 
 Wanna take a look at the documentation project?
 
 	http://www.freebsd.org/docproj/docproj.html
 
 Ciao,
 Sheldon.
 
State-Changed-From-To: open->closed 
State-Changed-By: dd 
State-Changed-When: Mon Sep 3 11:08:39 PDT 2001 
State-Changed-Why:  
This section (which has been moved to the developers-handbook) seems 
pretty accurate to me.  makeoptions DEBUG=g *is* enough to get a kernel 
with debugging symbols. 

http://www.FreeBSD.org/cgi/query-pr.cgi?pr=20400 
>Unformatted:
