[src/trunk]: src/share/man/man5 mk.conf(5): update to reality

[lukem <lukem%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/0b1270eab0a1
branches:  trunk
changeset: 376117:0b1270eab0a1
user:      lukem <lukem%NetBSD.org@localhost>
date:      Thu Jun 01 21:58:05 2023 +0000

description:
mk.conf(5): update to reality

- Document:
        MKAMDGPUFIRMWARE, MKARGON2, MKARZERO, MKBSDGREP,
        MKCOMPATMODULES, MKCOMPATTESTS, MKCOMPATX11, MKCXX,
        MKDEPINCLUDES, MKDTB, MKDTC, MKFIRMWARE, MKGROFF,
        MKGROFFHTMLDOC, MKLIBCSANITIZER, MKLIBCXX, MKLIBSTDCXX,
        MKLLVM, MKLLVMRT, MKMAKEMANDB, MKMANDOC, MKNSD,
        MKRADEONFIRMWARE, MKRELRO, MKSANITIZER, MKSLJIT,
        MKSTATICPIE, MKTEGRAFIRMWARE, MKTPM, MKUNBOUND,
        MKXORG_SERVER, NETBSD_OFFICIAL_RELEASE,
        USE_LIBCSANITIZER, USE_PIGZGZIP, USE_SANITIZER,
        USE_XZ_SETS, X11MOTIFPATH
- Document obsolete/deprecated:
        EXTSRCSRCDIR, MKBFD, MKCRYPTO, MKEXTSRC, MKKDEBUG,
        MKKERBEROS4, MKLLD, MKLLDB, MKMCLINKER, MKPERFUSE,
        MKTOOLSDEBUG, SHAREDSTRINGS, USE_COMBINE
- Fix defaults: MKLINT=no MKPICINSTALL=no USE_SKEY=no
- Expand upon defaults that are platform specific.
- Sort variable entries.
- If a NOxxx variable disables a variable, describe it.
- Layout of each variable: supported values, description,
  any other variables that change this variable, optional note,
  default value.
- Consistent double quotes around default strings (even paths).
- Consistent "will be" instead of "is" or "are".
- Sort order of internal macro definitions.
- Add NODEF and NOVAR macros.
- Oxford comma and semi-colons where appropriate.
- Fix mandoc -Tlint.

diffstat:

 share/man/man5/mk.conf.5 |  1313 ++++++++++++++++++++++++++++++++++++---------
 1 files changed, 1045 insertions(+), 268 deletions(-)

diffs (truncated from 1890 to 300 lines):

diff -r 6d88df8c6a56 -r 0b1270eab0a1 share/man/man5/mk.conf.5
--- a/share/man/man5/mk.conf.5  Thu Jun 01 21:54:17 2023 +0000
+++ b/share/man/man5/mk.conf.5  Thu Jun 01 21:58:05 2023 +0000
@@ -1,6 +1,6 @@
-.\"    $NetBSD: mk.conf.5,v 1.97 2022/07/09 08:27:35 nia Exp $
+.\"    $NetBSD: mk.conf.5,v 1.98 2023/06/01 21:58:05 lukem Exp $
 .\"
-.\"  Copyright (c) 1999-2003 The NetBSD Foundation, Inc.
+.\"  Copyright (c) 1999-2023 The NetBSD Foundation, Inc.
 .\"  All rights reserved.
 .\"
 .\"  This code is derived from software contributed to The NetBSD Foundation
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd July 9, 2022
+.Dd June 1, 2022
 .Dt MK.CONF 5
 .Os
 .\" turn off hyphenation
@@ -50,16 +50,14 @@ relevant manual pages.
 .
 .Ss NetBSD System variables
 .
-.de YorN
-Can be set to
-.Dq yes
-or
-.Dq no .
-..
 .de DFLT
 .Pp
 .Em Default :
 ..
+.de DFLTn
+.DFLT
+.Dq no
+..
 .de DFLTu
 .DFLT
 Unset.
@@ -68,44 +66,51 @@ Unset.
 .DFLT
 .Dq yes
 ..
-.de DFLTn
-.DFLT
+.de NODEF
+.Pp
+Forced to
 .Dq no
+if
+.Sy \\$*
+is defined,
+usually in the Makefile before any
+.Xr make 1
+.Cm \&.include
+directives.
 ..
-.Bl -tag -width MKDYNAMICROOT
+.de NOVAR
+.Pp
+Forced to
+.Dq no
+if
+.Sy \\$* .
+..
+.de YorN
+Can be set to
+.Dq yes
+or
+.Dq no .
+..
 .
-.It Sy NETBSDSRCDIR
-The path to the top level of the
-.Nx
-sources.
-If
-.Xr make 1
-is run from within the
-.Nx
-source tree, the default is the top
-level of that tree (as determined by the presence of
-.Pa build.sh
-and
-.Pa tools/ ) ,
-otherwise
-.Sy BSDSRCDIR
-will be used.
+.Bl -tag -width 15n
+.
+.\" These entries are sorted alphabetically
 .
 .It Sy BSDOBJDIR
-The real path to the
-.Sq obj
-tree for the
+The real path to the object directory tree for the
 .Nx
 source tree.
 .DFLT
-.Pa /usr/obj
+.Dq Pa /usr/obj
 .
 .It Sy BSDSRCDIR
 The real path to the
 .Nx
-source tree.
+source tree, if
+.Sy NETBSDSRCDIR
+isn't defined.
 .DFLT
-.Pa /usr/src
+.Dq Pa /usr/src
 .
 .It Sy BUILD
 If defined,
@@ -165,24 +170,25 @@ character (for installation into the sys
 to an empty string).
 The directory must reside on a file system which supports long file
 names and hard links.
-.DFLT
-Empty string if
-.Sy USETOOLS
-is
-.Dq yes ;
-unset otherwise.
 .Pp
 .Em Note :
 .Sy build.sh
 will provide a default of
-.Pa destdir. Ns Sy MACHINE
+.Dq Pa destdir . Ns Sy MACHINE
 (in the top-level
 .Sy .OBJDIR )
 unless run in
 .Sq expert
 mode
+.DFLT
+Empty string if
+.Sy USETOOLS=yes ;
+unset otherwise.
 .
-.It Sy KERNEL_DIR No Pq experimental
+.It Sy EXTSRCSRCDIR
+Obsolete.
+.
+.It Sy KERNEL_DIR Pq No experimental
 .YorN
 Indicates if a top-level directory
 .Sy /netbsd/
@@ -216,7 +222,7 @@ It is also subject to change without not
 .It Sy MAKEVERBOSE
 Level of verbosity of status messages.
 Supported values:
-.Bl -tag -width xxx
+.Bl -tag -width 2n
 .It 0
 No descriptive messages or commands executed by
 .Xr make 1
@@ -250,18 +256,57 @@ flag.
 .DFLT
 2
 .
+.It Sy MKAMDGPUFIRMWARE
+.YorN
+Indicates whether to install the
+.Pa /libdata/firmware/amdgpu
+directory, which is necessary for the
+.Xr amdgpu 4
+AMD RADEON GPU video driver.
+.DFLTy
+on
+.Sy i386
+and
+.Sy x86_64 ;
+.Dq no
+on other platforms.
+.
+.It Sy MKARGON2
+.YorN
+Indicates whether the Argon2 hash is enabled in libcrypt.
+.DFLTy
+.
+.It Sy MKARZERO
+.YorN
+Indicates whether
+.Xr ar 1
+should zero the timestamp, uid, and gid in the archive
+for reproducible builds.
+.DFLT
+The value of
+.Sy MKREPRO
+(if defined), otherwise
+.Dq no .
+.
 .It Sy MKATF
 .YorN
-Indicates whether the Automated Testing Framework is built and installed.
+Indicates whether the Automated Testing Framework (ATF)
+will be built and installed.
 This also controls whether the
 .Nx
-test suite is built and installed,
+test suite will be built and installed,
 as the tests rely on ATF and cannot be built without it.
+.NOVAR MKCXX=no
 .DFLTy
 .
+.It Sy MKBFD
+Obsolete, use
+.Sy MKBINUTILS .
+.
 .It Sy MKBINUTILS
 .YorN
-Indicates whether any of the binutils tools or libraries should be built.
+Indicates whether any of the binutils tools or libraries
+will be built and installed.
 That is, the libraries
 .Sy libbfd ,
 .Sy libiberty ,
@@ -271,28 +316,46 @@ or any of the things that depend upon th
 .Xr dbsym 8 ,
 or
 .Xr mdsetimage 8 .
+.NOVAR TOOLCHAIN_MISSING!=no
 .DFLTy
 .
+.It Sy MKBSDGREP
+.YorN
+Determines which implementation of
+.Xr grep 1
+will be built and installed.
+If
+.Dq yes ,
+use the BSD implementation.
+If
+.Dq no ,
+use the GNU implementation.
+.DFLTn
+.
 .It Sy MKBSDTAR
 .YorN
-If
-.Dq yes ,
-.Sy libarchive Ns - Ns
-based implementations of
+Determines which implementation of
 .Xr cpio 1
 and
 .Xr tar 1
-are built and installed.
+will be built and installed.
+If
+.Dq yes ,
+use the
+.Sy libarchive Ns - Ns
+based implementations.
 If
 .Dq no ,
+use the
 .Xr pax 1
-based frontends are used.
+based implementations.
 .DFLTy
 .
 .It Sy MKCATPAGES
 .YorN
 Indicates whether preformatted plaintext manual pages will be created
 and installed.
+.NOVAR MKMAN=no No or Sy MKSHARE=no
 .DFLTn
 .
 .It Sy MKCLEANSRC
@@ -343,10 +406,47 @@ then file deletions will not be verified
 .YorN
 Indicates whether support for multiple ABIs is to be built and
 installed.
+.NODEF NOCOMPAT
 .DFLTy
-on amd64, mips64 and sparc64,
+on
+.Sy aarch64
+(without gcc),
+.Sy mips64 ,
+.Sy powerpc64 ,
+.Sy riscv64 ,
+.Sy sparc64 ,
+and
+.Sy x86_64 ;
 .Dq no
-on other architectures.
+on other platforms.
+.
+.It Sy MKCOMPATMODULES
+.YorN
+Indicates whether the compat kernel modules will be built and installed.
+.NOVAR MKCOMPAT=no