Bug 20400

Summary:	Building a kernel with debugging info section could use a rework
Product:	Documentation	Reporter:	jefblaine <jefblaine>
Component:	Books & Articles	Assignee:	freebsd-doc (Nobody) <doc>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description jefblaine 2000-08-04 15:30:01 UTC

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'...

Comment 1 Sheldon Hearn 2000-08-04 15:46:27 UTC

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.

Comment 2 dd freebsd_committer

2001-09-03 19:08:39 UTC

State Changed
From-To: open->closed

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.