[src/trunk]: src/share/man/man5 mk.conf(5): more variables from BUILDING and ...

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

details:   https://anonhg.NetBSD.org/src/rev/a6daf7af9051
branches:  trunk
changeset: 376343:a6daf7af9051
user:      lukem <lukem%NetBSD.org@localhost>
date:      Sun Jun 11 20:33:46 2023 +0000

description:
mk.conf(5): more variables from BUILDING and build.sh

Add more variables from build.sh, BUILDING, and various
Makefile's documentation:
        CDEXTRA CONFIGOPTS KERNARCHDIR KERNCONFDIR
        KERNOBJDIR KERNSRCDIR LOCALTIME

Default sentences now consistently end with ".".
Consistency tweaks in "otherwise".
Editorial tweaks.

diffstat:

 share/man/man5/mk.conf.5 |  237 ++++++++++++++++++++++++++++++++++------------
 1 files changed, 175 insertions(+), 62 deletions(-)

diffs (truncated from 614 to 300 lines):

diff -r 766c3aea5c7c -r a6daf7af9051 share/man/man5/mk.conf.5
--- a/share/man/man5/mk.conf.5  Sun Jun 11 17:54:18 2023 +0000
+++ b/share/man/man5/mk.conf.5  Sun Jun 11 20:33:46 2023 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: mk.conf.5,v 1.102 2023/06/11 10:44:33 lukem Exp $
+.\"    $NetBSD: mk.conf.5,v 1.103 2023/06/11 20:33:46 lukem Exp $
 .\"
 .\"  Copyright (c) 1999-2023 The NetBSD Foundation, Inc.
 .\"  All rights reserved.
@@ -62,7 +62,7 @@ and the default value of each variable.
 ..
 .de DFLTn
 .DFLT
-.Dq no
+.Dq no .
 ..
 .de DFLTu
 .DFLT
@@ -70,7 +70,7 @@ Unset.
 ..
 .de DFLTy
 .DFLT
-.Dq yes
+.Dq yes .
 ..
 .de NODEF
 .Pp
@@ -107,7 +107,7 @@ The real path to the object directory tr
 .Nx
 source tree.
 .DFLT
-.Dq Pa /usr/obj
+.Dq Pa /usr/obj .
 .
 .It Sy BSDSRCDIR
 The real path to the
@@ -116,14 +116,18 @@ source tree, if
 .Sy NETBSDSRCDIR
 isn't defined.
 .DFLT
-.Dq Pa /usr/src
+.Dq Pa /usr/src .
 .
 .It Sy BUILD
 If defined,
 .Sq "make install"
-checks that the targets in the source directories are up-to-date and
+checks that the
+.Xr make 1
+targets in the source directories are up-to-date and
 re-makes them if they are out of date, instead of blindly trying to install
-out of date or non-existent targets.
+out of date or non-existent
+.Xr make 1
+targets.
 .DFLTu
 .
 .It Sy BUILDID
@@ -177,6 +181,33 @@ documentation of
 .Fl frandom-seed .
 .DFLTu
 .
+.It Sy CDEXTRA
+A space-separated list of files or directories that will be
+added to the CD-ROM image that may be create by the
+.Sy build.sh
+.Dq iso-image
+or
+.Dq iso-image-source
+operations.
+Files will be added to the root of the CD-ROM image,
+whereas directories will be copied recursively.
+If relative paths are specified, they will be converted to
+absolute paths before being used.
+.Em Note :
+If using
+.Sy build.sh ,
+multiple paths may be specified via multiple
+.Fl C
+options, or via a single option whose argument contains multiple
+space-separated paths.
+.DFLTu
+.
+.It Sy CONFIGOPTS
+Additional flags to
+.Xr config 1
+when building kernels.
+.DFLTu
+.
 .It Sy COPTS
 Extra options for the C compiler.
 Should be appended to (e.g.,
@@ -234,11 +265,13 @@ will provide a default of
 .Sy .OBJDIR )
 unless run in
 .Sq expert
-mode.
+mode with the
+.Fl E
+option.
 .DFLT
 Empty string if
 .Sy USETOOLS=yes ;
-unset otherwise.
+otherwise unset.
 .
 .It Sy EXTERNAL_TOOLCHAIN
 If defined, this variable indicates the root directory of
@@ -283,12 +316,25 @@ option of
 .DFLTu
 .
 .It Sy INSTALLWORLDDIR
-Location for the top-level
-.Dq make installworld
+Directory for the top-level
+.Xr make 1
+.Dq installworld
 target to install to.
 If specified, must be an absolute path.
 .DFLT
-.Dq /
+.Dq Pa / .
+.
+.It Sy KERNARCHDIR
+Directory under
+.Sy KERNSRCDIR
+containing the machine dependent kernel sources.
+.DFLT
+.Dq Pa arch/ Ns Sy MACHINE .
+.
+.It Sy KERNCONFDIR
+Directory containing the kernel configuration files.
+.DFLT
+.Dq Sy KERNSRCDIR Ns Pa / Ns Sy KERNARCHDIR Ns Pa /conf .
 .
 .It Sy KERNEL_DIR Pq No experimental
 .YorN
@@ -321,6 +367,38 @@ The
 option is a work-in-progress, and is highly experimental.
 It is also subject to change without notice.
 .DFLTn
+.
+.It Sy KERNOBJDIR
+Directory for kernel builds.
+For example, the kernel
+.Sy GENERIC
+will be compiled in
+.Sy KERNOBJDIR Ns Pa /GENERIC .
+.DFLT
+.Dq Sy MAKEOBJDIRPREFIX Ns Pa / Ns Sy KERNSRCDIR Ns Pa / Ns Sy KERNARCHDIR Ns Pa /compile
+if it exists or the
+.Xr make 1
+.Dq obj
+target is being made;
+otherwise
+.Dq Sy KERNSRCDIR Ns Pa / Ns Sy KERNARCHDIR Ns Pa /compile .
+.
+.It Sy KERNSRCDIR
+Directory at the top of the kernel source.
+.DFLT
+.Dq Sy NETBSDSRCDIR Ns Pa /sys .
+.
+.It Sy LOCALTIME
+The name of the
+.Xr tzfile 5
+timezone file in the directory
+.Pa /usr/share/zoneinfo
+to symbolically link
+.Sy DESTDIR Ns Pa /etc/localtime
+to.
+.DFLT
+.Dq UTC .
+.
 .It Sy MAKEVERBOSE
 Level of verbosity of status messages.
 Supported values:
@@ -356,7 +434,7 @@ are traced through use of the
 flag.
 .El
 .DFLT
-2
+.Sy 2 .
 .
 .It Sy MKAMDGPUFIRMWARE
 .YorN
@@ -365,7 +443,8 @@ Indicates whether to install the
 directory, which is necessary for the
 .Xr amdgpu 4
 AMD RADEON GPU video driver.
-.DFLTy
+.DFLT
+.Dq yes
 on
 .Sy i386
 and
@@ -505,7 +584,8 @@ then file deletions will not be verified
 Indicates whether support for multiple ABIs is to be built and
 installed.
 .NODEF NOCOMPAT
-.DFLTy
+.DFLT
+.Dq yes
 on
 .Sy aarch64
 (without gcc),
@@ -522,7 +602,8 @@ on other platforms.
 .YorN
 Indicates whether the compat kernel modules will be built and installed.
 .NOVAR MKCOMPAT=no
-.DFLTy
+.DFLT
+.Dq yes
 on
 .Sy evbppc-powerpc
 and
@@ -570,7 +651,8 @@ CTF data of ELF binaries during build.
 .Pp
 This is disabled internally for standalone programs in
 .Pa /usr/mdec .
-.DFLTy
+.DFLT
+.Dq yes
 on
 .Sy aarch64 ,
 .Sy amd64 ,
@@ -602,9 +684,9 @@ and acts as
 Indicates whether debug information should be generated for
 all userland binaries.
 The result is collected as an additional
-.Sy debug.tgz
+.Sy debug
 and
-.Sy xdebug.tgz
+.Sy xdebug
 set and installed in
 .Sy DESTDIR Ns Pa /usr/libdata/debug .
 .NODEF NODEBUG
@@ -669,7 +751,8 @@ will be installed.
 .It Sy MKDTB
 .YorN
 Indicates whether the devicetree blobs will be built and installed.
-.DFLTy
+.DFLT
+.Dq yes
 on
 .Sy aarch64 ,
 .Sy armv6 ,
@@ -690,7 +773,8 @@ Indicates whether the Device Tree Compil
 Indicates whether the kernel modules, utilities, and libraries for
 .Xr dtrace 1
 support are to be built and installed.
-.DFLTy
+.DFLT
+.Dq yes
 on
 .Sy aarch64 ,
 .Sy amd64 ,
@@ -717,7 +801,8 @@ link programs in
 and
 .Pa /sbin
 statically.
-.DFLTn
+.DFLT
+.Dq no
 on
 .Sy ia64 ;
 .Dq yes
@@ -744,7 +829,8 @@ directory, which is necessary for variou
 .Xr wpi 4 ,
 .Xr zyd 4 ,
 and the Tegra 124 SoC.
-.DFLTy
+.DFLT
+.Dq yes
 on
 .Sy amd64 ,
 .Sy cobalt ,
@@ -784,7 +870,8 @@ then
 controls if the
 GCC libraries will be built and installed.
 .NOVAR MKCXX=no
-.DFLTn
+.DFLT
+.Dq no
 on
 .Sy m68000 ;
 .Dq yes
@@ -796,7 +883,8 @@ Indicates whether
 .Xr gdb 1
 will be built and installed.
 .NOVAR MKCXX=no No or Sy TOOLCHAIN_MISSING!=no
-.DFLTn
+.DFLT
+.Dq no
 on
 .Sy ia64
 and
@@ -893,7 +981,8 @@ programs, headers, and other components 
 .YorN
 Indicates whether the iSCSI library and applications are