[src/trunk]: src/share/man/man5 mk.conf(5): add remaining vars from BUILDING

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

details:   https://anonhg.NetBSD.org/src/rev/3ec59c475147
branches:  trunk
changeset: 376339:3ec59c475147
user:      lukem <lukem%NetBSD.org@localhost>
date:      Sun Jun 11 10:44:33 2023 +0000

description:
mk.conf(5): add remaining vars from BUILDING

Add more variables from BUILDING:
        INSTALLBOOT_BOARDS INSTALLWORLDDIR NOCLEANDIR
        NODISTRIBDIRS NOINCLUDES.

Add build.sh related notes (from BUILDING).

Clarify "target" as "target architecture" where appropriate
(versus a make target where that's obvious from context.)

Move all obsolete and deprecated variables to
new "OBSOLETE VARIABLES" section at the end.

Add some per-variable editorial improvements from BUILDING.

Change sub headings to headings; it's easier to read.
(I don't know why mdoc doesn't allow blank lines around .Ss)

diffstat:

 share/man/man5/mk.conf.5 |  285 ++++++++++++++++++++++++++++++++++++----------
 1 files changed, 219 insertions(+), 66 deletions(-)

diffs (truncated from 546 to 300 lines):

diff -r e7813d8b7f7f -r 3ec59c475147 share/man/man5/mk.conf.5
--- a/share/man/man5/mk.conf.5  Sun Jun 11 10:43:51 2023 +0000
+++ b/share/man/man5/mk.conf.5  Sun Jun 11 10:44:33 2023 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: mk.conf.5,v 1.101 2023/06/05 22:35:20 lukem Exp $
+.\"    $NetBSD: mk.conf.5,v 1.102 2023/06/11 10:44:33 lukem Exp $
 .\"
 .\"  Copyright (c) 1999-2023 The NetBSD Foundation, Inc.
 .\"  All rights reserved.
@@ -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 June 5, 2023
+.Dd June 11, 2023
 .Dt MK.CONF 5
 .Os
 .\" turn off hyphenation
@@ -41,14 +41,20 @@
 The
 .Nm
 file overrides various parameters used during the build of the system.
-.Pp
+.
+.Sh NETBSD SYSTEM VARIABLES
+.
 Listed below are the
 .Nm
-variables that may be set, the values to which each may be set,
-a brief description of what each variable does, and a reference to
-relevant manual pages.
-.
-.Ss NetBSD System variables
+variables that may be set that affect the
+.Nx NetBSD
+system build,
+the values to which each may be set,
+a brief description of what each variable does,
+references to relevant manual pages,
+notes (including any interaction with
+.Sy build.sh ) ,
+and the default value of each variable.
 .
 .de DFLT
 .Pp
@@ -190,12 +196,15 @@ should never be set in
 .Nm .
 .
 .It Sy CPUFLAGS
-Additional flags passed to the compiler/assembler to select
+Additional options passed to the compiler/assembler to select
 CPU instruction set options, CPU tuning options, etc.
+.Pp
+.Em Note :
 Such options should not be specified in
 .Sy COPTS ,
 because some parts of the build process need to override
 CPU-related compiler options.
+.DFLTu
 .
 .It Sy DESTDIR
 Directory to contain the built
@@ -205,13 +214,15 @@ If set, special options are passed to th
 prevent their default use of the host system's
 .Sy /usr/include , /usr/lib ,
 and so forth.
-This pathname should
+This pathname must be an absolute path, and should
 .Em not
 end with a slash
 .Pq /
-character (for installation into the system's root directory, set
+character.
+(For installation into the system's root directory, set
 .Sy DESTDIR
-to an empty string).
+to an empty string, not to
+.Dq / ) .
 The directory must reside on a file system which supports long file
 names and hard links.
 .Pp
@@ -223,7 +234,7 @@ will provide a default of
 .Sy .OBJDIR )
 unless run in
 .Sq expert
-mode
+mode.
 .DFLT
 Empty string if
 .Sy USETOOLS=yes ;
@@ -257,8 +268,27 @@ Expect the exact semantics of this varia
 term as parts of the cross-compile framework continue to be cleaned up.
 .DFLTu
 .
-.It Sy EXTSRCSRCDIR
-Obsolete.
+.It Sy INSTALLBOOT_BOARDS
+A list of
+.Sy evbarm
+boards to create bootable images for.
+If corresponding U-Boot packages are installed,
+bootable images are created as part of a release.
+See the
+.Bk -words
+.Fl o Sy board= Ns Ar name
+.Ek
+option of
+.Xr installboot 8 .
+.DFLTu
+.
+.It Sy INSTALLWORLDDIR
+Location for the top-level
+.Dq make installworld
+target to install to.
+If specified, must be an absolute path.
+.DFLT
+.Dq /
 .
 .It Sy KERNEL_DIR Pq No experimental
 .YorN
@@ -303,17 +333,17 @@ are shown.
 Brief messages are shown describing what is being done,
 but the actual commands executed by
 .Xr make 1
-are not displayed.
+are not shown.
 .It 2
 Descriptive messages are shown as above (prefixed with a
 .Sq # ) ,
 and ordinary commands performed by
 .Xr make 1
-are displayed.
+are shown.
 .It 3
 In addition to the above, all commands performed by
 .Xr make 1
-are displayed, even if they would ordinarily have been hidden
+are shown, even if they would ordinarily have been hidden
 through use of the
 .Dq \&@
 prefix in the relevant makefile.
@@ -371,10 +401,6 @@ as the tests rely on ATF and cannot be b
 .NOVAR MKCXX=no
 .DFLTy
 .
-.It Sy MKBFD
-Obsolete, use
-.Sy MKBINUTILS .
-.
 .It Sy MKBINUTILS
 .YorN
 Indicates whether any of the binutils tools or libraries
@@ -533,9 +559,6 @@ is compiled with support for
 Create a cross-gdb as a host tool.
 .DFLTn
 .
-.It Sy MKCRYPTO
-Obsolete.
-.
 .It Sy MKCTF
 .YorN
 Indicates whether CTF tools are to be built and installed.
@@ -700,9 +723,6 @@ on
 .Dq yes
 on other platforms.
 .
-.It Sy MKEXTSRC
-Obsolete.
-.
 .It Sy MKFIRMWARE
 .YorN
 Indicates whether to install the
@@ -819,11 +839,12 @@ will be suffixed to the name of the obje
 .Dq make obj .
 (This allows multiple host systems to compile
 .Nx
-for a single target.)
+for a single target architecture.)
 If
 .Dq no ,
 then programs built to be run on the compile host will use the same
-object directory names as programs built to be run on the target.
+object directory names as programs built to be run on the target
+architecture.
 .DFLTn
 .
 .It Sy MKHTML
@@ -878,10 +899,6 @@ on
 .Dq yes
 on other platforms.
 .
-.It Sy MKKDEBUG
-Deprecated, use
-.Sy MKDEBUGKERNEL .
-.
 .It Sy MKKERBEROS
 .YorN
 Indicates whether the Kerberos v5 infrastructure
@@ -897,9 +914,6 @@ files or disabling PAM via
 Otherwise all logins will fail.
 .DFLTy
 .
-.It Sy MKKERBEROS4
-Obsolete.
-.
 .It Sy MKKMOD
 .YorN
 Indicates whether kernel modules will be built and installed.
@@ -1009,12 +1023,6 @@ installed into
 .NOVAR MKLINKLIB=no
 .DFLTn
 .
-.It Sy MKLLD
-Obsolete.
-.
-.It Sy MKLLDB
-Obsolete.
-.
 .It Sy MKLLVM
 .YorN
 Indicates whether
@@ -1115,9 +1123,6 @@ Only used if
 .Sy MKMAN=yes .
 .DFLTn
 .
-.It Sy MKMCLINKER
-Obsolete.
-.
 .It Sy MKMDNS
 .YorN
 Indicates whether the mDNS (Multicast DNS) infrastructure
@@ -1188,6 +1193,19 @@ Indicates whether object directories wil
 .Dq make obj
 pass) at the start of a build.
 .NOVAR MKOBJ=no
+.Pp
+.Em Note :
+If using
+.Sy build.sh ,
+the default is
+.Dq yes .
+This may be set back to
+.Dq no
+by giving
+.Sy build.sh
+the
+.Fl o
+option.
 .DFLTn
 .
 .It Sy MKPAM
@@ -1207,9 +1225,6 @@ or any related libraries
 will be built and installed.
 .DFLTn
 .
-.It Sy MKPERFUSE
-Obsolete.
-.
 .It Sy MKPF
 .YorN
 Indicates whether the
@@ -1373,6 +1388,15 @@ results.
 .Pp
 Used as the default for
 .Sy MKARZERO .
+.Pp
+.Em Note :
+This may be set to
+.Dq yes
+by giving
+.Sy build.sh
+the
+.Fl P
+option.
 .DFLTn
 .
 .It Sy MKREPRO_TIMESTAMP
@@ -1381,6 +1405,16 @@ When
 .Sy MKREPRO
 is set, the timestamp of all files in the sets will be set
 to this value.
+.Pp
+.Em Note :
+This may be set automatically to the latest source tree timestamp
+using
+.Xr cvslatest 1
+by giving
+.Sy build.sh
+the
+.Fl P
+option.
 .DFLTu
 .
 .It Sy MKRUMP
@@ -1519,10 +1553,6 @@ on
 .Dq no
 on other platforms.
 .
-.It Sy MKTOOLSDEBUG
-Deprecated, use