[src/trunk]: src/share/man/man5 mk.conf(5): editorial

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

details:   https://anonhg.NetBSD.org/src/rev/441fa0992417
branches:  trunk
changeset: 376242:441fa0992417
user:      lukem <lukem%NetBSD.org@localhost>
date:      Mon Jun 05 22:35:20 2023 +0000

description:
mk.conf(5): editorial

MKDTB and MKPIE are .YorN.
MKX11=yes wants MKINET6=yes.
MKLINKLIB deserves a dash list (like bsd.README).

Expand per bsd.README: MKSTATICPIC, MKUNPRIVED,
MKX11, MKZFS, USE_LIBCSANITIZER, USE_SSP

Change the width of the variable lists to 14n (from 15n)
so that when the lists are rendered and then left aligned,
the column is 16 characters (aka 2 tabs) which makes
copypasta to bsd.README easier.

diffstat:

 share/man/man5/mk.conf.5 |  70 +++++++++++++++++++++++++++++++++++++++--------
 1 files changed, 58 insertions(+), 12 deletions(-)

diffs (188 lines):

diff -r c67025b71278 -r 441fa0992417 share/man/man5/mk.conf.5
--- a/share/man/man5/mk.conf.5  Mon Jun 05 20:56:18 2023 +0000
+++ b/share/man/man5/mk.conf.5  Mon Jun 05 22:35:20 2023 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: mk.conf.5,v 1.100 2023/06/04 20:04:52 lukem Exp $
+.\"    $NetBSD: mk.conf.5,v 1.101 2023/06/05 22:35:20 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 4, 2023
+.Dd June 5, 2023
 .Dt MK.CONF 5
 .Os
 .\" turn off hyphenation
@@ -92,7 +92,7 @@ or
 .Dq no .
 ..
 .
-.Bl -tag -width 15n
+.Bl -tag -width 14n
 .
 .\" These entries are sorted alphabetically.
 .
@@ -644,6 +644,7 @@ will be installed.
 .DFLTy
 .
 .It Sy MKDTB
+.YorN
 Indicates whether the devicetree blobs will be built and installed.
 .DFLTy
 on
@@ -843,6 +844,13 @@ Has no effect on most platforms.
 .YorN
 Indicates whether INET6 (IPv6) infrastructure
 (libraries and support programs) will be built and installed.
+.Pp
+.Em Note :
+.Sy MKINET6
+must not be set to
+.Dq no
+if
+.Sy MKX11!=no .
 .DFLTy
 .
 .It Sy MKINFO
@@ -954,22 +962,32 @@ Indicates if libstdc++ will be built and
 .YorN
 Indicates whether all of the shared library infrastructure
 will be built and installed.
+.Pp
 If
 .Dq no ,
 prevents:
+.Bl -dash -compact
+.It
 installation of the
 .Sy *.a
-libraries,
+libraries
+.It
 installation of the
 .Sy *_pic.a
-libraries on PIC systems,
+libraries on PIC systems
+.It
 building of
 .Sy *.a
-libraries on PIC systems,
-or
+libraries on PIC systems
+.It
 installation of
 .Sy .so
-symlinks on ELF systems.
+symlinks on ELF systems
+.El
+.Pp
+I.e, only install the shared library (and the
+.Pa .so.major
+symlink on ELF).
 .NODEF NOLINKLIB
 .Pp
 If
@@ -1244,6 +1262,7 @@ on
 on other platforms.
 .
 .It Sy MKPIE
+.YorN
 Indicates whether Position Independent Executables (PIE)
 will be built and installed.
 .NODEF NOPIE
@@ -1448,6 +1467,8 @@ will be built and installed.
 .YorN
 Indicates whether support for static PIE binaries
 will be built and installed.
+These binaries use a special support in crt0.o for
+resolving relative relocations and require linker support.
 .DFLTy
 on
 .Sy i386
@@ -1528,6 +1549,8 @@ The contents of
 .Pa METALOG
 is used during the generation of the distribution tar files to ensure
 that the appropriate file ownership is stored.
+This allows a non-root
+.Sq "make install" .
 .DFLTn
 .
 .It Sy MKUPDATE
@@ -1541,7 +1564,14 @@ phase if the destination files are up-to
 .It Sy MKX11
 .YorN
 Indicates whether X11 will be built and installed from
-.Sy X11SRCDIR .
+.Sy X11SRCDIR ,
+and whether the X sets will be created.
+.Pp
+.Em Note :
+If
+.Dq yes ,
+requires
+.Sy MKINET6=yes .
 .DFLTn
 .
 .It Sy MKX11FONTS
@@ -1549,6 +1579,7 @@ Indicates whether X11 will be built and 
 If
 .Dq no ,
 do not build and install the X fonts.
+The xfont set is still created but will be empty.
 .Pp
 Only used if
 .Sy MKX11=yes .
@@ -1616,6 +1647,9 @@ Indicates whether the YP (NIS) infrastru
 .YorN
 Indicates whether the ZFS kernel module and the utilities and
 libraries used to manage the ZFS system are to be built and installed.
+.Pp
+.Em Note :
+ZFS requires 64-bit atomic operations .
 .DFLTy
 on
 .Sy aarch64 ,
@@ -1823,9 +1857,17 @@ Supported values:
 .Bl -tag -width undefined
 .It undefined
 Enables the micro-UBSan in the user mode (uUBSan)
-undefined behaviour sanitizer, with
+undefined behaviour sanitizer.
+The code is shared with the kernel mode variation (kUBSan).
+The runtime runtime differs from the UBSan available in
+.Sy MKSANITIZER .
+The runtime is stripped down from C++ features,
+and is invoked with
 .Li -fsanitize=no-vptr
 as that sanitizer is not supported.
+The runtime configuration is restricted to the
+.Ev LIBC_UBSAN
+environment variable, that is designed to be safe for hardening.
 .El
 .Pp
 The value of
@@ -1912,7 +1954,8 @@ This is mutually exclusive to
 Indicates whether GCC stack-smashing protection (SSP) support,
 which detects stack overflows and aborts the program,
 is enabled.
-This imposes some performance penalty.
+This imposes some performance penalty
+(approximately 5%).
 .Pp
 This is disabled internally for standalone programs in
 .Pa /usr/mdec .
@@ -1926,7 +1969,10 @@ on
 and
 .Sy mips ;
 .Dq yes
-on other platforms.
+on other platforms if
+.Sy USE_FORT=yes ;
+.Dq no
+otherwise.
 .
 .It Sy USE_XZ_SETS
 .YorN