From 59c9abb9cfdcc74007e3306af1e5fa3fa6d7de65 Mon Sep 17 00:00:00 2001
From: Gordon Bergling <gbe@FreeBSD.org>
Date: Sat, 3 Oct 2020 14:45:17 +0000
Subject: [PATCH] MFC r365640: Improvements for the src.conf(5) and build(7)
 man pages

PR:	203863 (based on)
Submitted by:	Russell Haley <russ dot haley at gmail dot com>
Reviewed by:	bcr, imp
Approved by:	imp
Differential Revision:	https://reviews.freebsd.org/D26343
---
 share/man/man5/src.conf.5   |  3 ++-
 share/man/man7/build.7      | 27 +++++++++++++++++++++------
 tools/build/options/makeman |  3 ++-
 3 files changed, 25 insertions(+), 8 deletions(-)

diff --git a/share/man/man5/src.conf.5 b/share/man/man5/src.conf.5
index 131d49696c2..d18b10fee06 100644
--- a/share/man/man5/src.conf.5
+++ b/share/man/man5/src.conf.5
@@ -9,7 +9,8 @@
 .Sh DESCRIPTION
 The
 .Nm
-file contains settings that will apply to every build involving the
+file contains variables that control what components will be generated during
+the build process of the
 .Fx
 source tree; see
 .Xr build 7 .
diff --git a/share/man/man7/build.7 b/share/man/man7/build.7
index 54811bf7e46..9cd9cc8e2f6 100644
--- a/share/man/man7/build.7
+++ b/share/man/man7/build.7
@@ -24,12 +24,12 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 10, 2018
+.Dd September 11, 2020
 .Dt BUILD 7
 .Os
 .Sh NAME
 .Nm build
-.Nd information on how to build the system
+.Nd General instructions on how to build the system
 .Sh DESCRIPTION
 The sources for the
 .Fx
@@ -68,10 +68,11 @@ command is used in each of these directories to build and install the
 things in that directory.
 Issuing the
 .Xr make 1
-command in any directory or
-subdirectory of those directories has the same effect as issuing the
-same command in all subdirectories of that directory.
-With no target specified, the things in that directory are just built.
+command in any directory issues the
+.Xr make 1
+command recursively in all subdirectories.
+With no target specified, the items in the directories are built
+and no further action is taken.
 .Pp
 A source tree is allowed to be read-only.
 As described in
@@ -95,6 +96,14 @@ variables described in the
 section below, and by the variables documented in
 .Xr make.conf 5 .
 .Pp
+The default components included in the build are specified in the file
+.Pa /etc/src.conf
+in the source tree.
+To override the default file, include the SRCCONF option in the make steps,
+pointing to a custom src.conf file.
+For more information see
+.Xr src.conf 5 .
+.Pp
 The following list provides the names and actions for the targets
 supported by the build system:
 .Bl -tag -width ".Cm cleandepend"
@@ -573,6 +582,12 @@ process.
 .Bd -literal -offset indent
 make PORTS_MODULES=emulators/kqemu-kmod kernel
 .Ed
+.It Va SRCCONF
+Specify a file to override the default
+.Pa /etc/src.conf .
+The src.conf file controls the components to build.
+See
+.Xr src.conf 5
 .It Va STRIPBIN
 Command to use at install time when stripping binaries.
 Be sure to add any additional tools required to run
diff --git a/tools/build/options/makeman b/tools/build/options/makeman
index 167571920dc..328b9faed88 100755
--- a/tools/build/options/makeman
+++ b/tools/build/options/makeman
@@ -154,7 +154,8 @@ main()
 .Sh DESCRIPTION
 The
 .Nm
-file contains settings that will apply to every build involving the
+file contains variables that control what components will be generated during
+the build process of the
 .Fx
 source tree; see
 .Xr build 7 .
-- 
2.45.0