kern/54438: makeoptions DEBUG="-g" documentation looks wrong

[gson%gson.org@localhost (Andreas Gustafsson)]

>Number:         54438
>Category:       kern
>Synopsis:       makeoptions DEBUG="-g" documentation looks wrong
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Aug 05 15:05:00 +0000 2019
>Originator:     Andreas Gustafsson
>Release:        NetBSD-current
>Organization:

>Environment:
System: NetBSD
Architecture: x86_64
Machine: amd64
>Description:

The options(4) man page says:

     makeoptions DEBUG="-g"
     The -g flag causes netbsd.gdb to be built in addition to netbsd.
     netbsd.gdb is useful for debugging kernel crash dumps with gdb.  See
     gdb(1) for details.  This also turns on options DEBUG (which see).

I don't think the statement "This also turns on options DEBUG" is
actually true.  For example, running "config -x" on a daily snapshot
from http://nycdn.netbsd.org/pub/NetBSD-daily/HEAD/latest/amd64/ shows
that it was built with makeoptions DEBUG="-g", but options DEBUG was
not turned on:

  #options        DEBUG           # expensive debugging checks/support
  makeoptions     DEBUG="-g"      # compile full symbol table for CTF

Also, running nm on /netbsd does not show functions that are
defined only within #ifdef DEBUG, such as uvm_pagezerocheck().

The text in case has been there since options.4 revision 1.1,
dated October 20, 1996.  Does anyone remember how and when it
stopped being true, if it was ever true?

Fixing this by making the code match the documentation would be bad,
because release kernels should have makeoptions DEBUG="-g" so that we
can generate CTF debug info for dtrace, but should not have options
DEBUG as that would make them "not suitable for regular use".
Therefore, I propose making the documentation match the code by
removing the text "This also turns on options DEBUG (which see)."
Any objections?

>How-To-Repeat:

>Fix: