Clarify the usage and effects of sys.mk, make.conf(5), and __MAKE_CONF.

MFC after:	2 weeks

share/man/man5/make.conf.5

@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd June 9, 2005
+.Dd October 10, 2005
 .Dt MAKE.CONF 5
 .Os
 .Sh NAME
@@ -33,47 +33,77 @@
 .Sh DESCRIPTION
 The file
 .Nm
-contains settings that control the compilation of the
-.Fx
-sources
-and ported applications.
+contains system-wide settings that will apply to every build using
+.Xr make 1
+and the standard
+.Pa sys.mk
+file.
+This is achieved as follows:
+.Xr make 1
+processes the system makefile
+.Pa sys.mk
+before any other file by default, and
+.Pa sys.mk
+includes
+.Nm .
+.Pp
 The file
 .Nm
-is generally created by the system administrator when the values need
-to be changed from their defaults.
-.Pp
-The purpose of
+uses the standard makefile syntax.
+However,
 .Nm
-is not to run commands or perform compilation actions
-directly.
-Instead, it is included by the
-various makefiles in
+should not specify any dependencies to
+.Xr make 1 .
+Instead,
+.Nm
+is to set
+.Xr make 1
+variables that control the actions of other makefiles.
+.Pp
+The default location of
+.Nm
+is
+.Pa /etc/make.conf ,
+though an alternative location can be specified in the
+.Xr make 1
+variable
+.Va __MAKE_CONF .
+You may need to override the location of
+.Nm
+if the system-wide settings are not suitable for a particular build.
+For instance, setting
+.Va __MAKE_CONF
+to
+.Pa /dev/null
+effectively resets all build controls to their defaults.
+.Pp
+The primary purpose of
+.Nm
+is to control the compilation of the
+.Fx
+sources, documentation, and ported applications,
+which are usually found in
 .Pa /usr/src ,
-.Pa /usr/ports
+.Pa /usr/doc ,
 and
-.Pa /usr/doc
-which conditionalize their
-internal actions according to the settings found there.
+.Pa /usr/ports .
+As a rule, the system administrator creates
+.Nm
+when the values of certain control variables need to be changed
+from their defaults.
 .Pp
-The
-.Pa /etc/make.conf
-file is included from the appropriate
-.Pa Makefile
-which specifies the default settings for all the available options.
-Options need only be specified in
-.Pa /etc/make.conf
-when the system administrator wishes to override these defaults.
-.Pp
-The build procedures occur in four broad areas: the world, the kernel,
-documentations and ports.
+The system build procedures occur in four broad areas:
+the world, the kernel, documentation and ports.
 Variables set in
 .Nm
-may be applicable during builds in one, two, or all four of these
-areas.
-They may be specified for a particular build via the
+may be applicable in one, two, or all four of these areas.
+In addition, control variables can be specified
+for a particular build via the
 .Fl D
 option of
-.Xr make 1 .
+.Xr make 1
+or in
+.Xr environ 7 .
 .Pp
 The following lists provide a name and short description for each
 variable you can use during the indicated builds.
@@ -834,6 +864,7 @@ This option is ignored if NO_CRYPTO or NO_OPENSSL are configured.
 .It Pa /etc/make.conf
 .It Pa /usr/doc/Makefile
 .It Pa /usr/share/examples/etc/make.conf
+.It Pa /usr/share/mk/sys.mk
 .It Pa /usr/src/Makefile
 .It Pa /usr/src/Makefile.inc1
 .El
@@ -841,6 +872,7 @@ This option is ignored if NO_CRYPTO or NO_OPENSSL are configured.
 .Xr gcc 1 ,
 .Xr install 1 ,
 .Xr make 1 ,
+.Xr environ 7 ,
 .Xr ports 7 ,
 .Xr lpd 8 ,
 .Xr sendmail 8

usr.bin/make/make.1

@@ -32,7 +32,7 @@
 .\"	@(#)make.1	8.8 (Berkeley) 6/13/95
 .\" $FreeBSD$
 .\"
-.Dd September 26, 2005
+.Dd October 10, 2005
 .Dt MAKE 1
 .Os
 .Sh NAME
@@ -188,8 +188,8 @@ Continue processing after errors are encountered, but only on those targets
 that do not depend on the target whose creation caused the error.
 .It Fl m Ar directory
 Specify a directory in which to search for
-.Pa sys.mk
-and makefiles included via the <...> style.
+the system makefile to process before any other file,
+as well as for makefiles included via the <...> style.
 Multiple directories can be added to form a search path.
 This path will override the default system include path:
 .Pa /usr/share/mk .
@@ -210,7 +210,7 @@ is used too.
 Do not execute any commands, but exit 0 if the specified targets are
 up-to-date and 1, otherwise.
 .It Fl r
-Do not use the built-in rules specified in the system makefile.
+Do not process the system makefile.
 .It Fl S
 Stop processing when an error is encountered.
 Default behaviour.
@@ -670,6 +670,12 @@ Makefiles may assign a colon-delimited list of directories to
 These directories will be searched for source files by
 .Nm
 after it has finished parsing all input makefiles.
+.It Va __MAKE_CONF
+This variable can specify an alternative location of
+.Xr make.conf 5
+for
+.Pa sys.mk
+to include.
 .El
 .Pp
 Variable expansion may be modified to select or modify each word of the
@@ -1451,6 +1457,9 @@ system makefile (processed before any other file, including
 .Pa makefile
 and
 .Pa Makefile )
+.It Pa /etc/make.conf
+default location of
+.Xr make.conf 5
 .It Pa /usr/share/mk
 system makefile directory
 .It /usr/share/doc/psd/12.make