From f43bc6d18d4e5d5c88302614caacfb085c62ae91 Mon Sep 17 00:00:00 2001
From: Bryan Drewery <bdrewery@FreeBSD.org>
Date: Thu, 14 Apr 2016 22:00:49 +0000
Subject: [PATCH] Add more content for WITH_META_MODE/WITH_DIRDEPS_BUILD.

Sponsored by:	EMC / Isilon Storage Division
---
 tools/build/options/WITH_DIRDEPS_BUILD | 20 ++++++--------
 tools/build/options/WITH_META_MODE     | 37 +++++++++++++++++++++++---
 2 files changed, 41 insertions(+), 16 deletions(-)

diff --git a/tools/build/options/WITH_DIRDEPS_BUILD b/tools/build/options/WITH_DIRDEPS_BUILD
index 981c1a93db11..334c483c9ca5 100644
--- a/tools/build/options/WITH_DIRDEPS_BUILD
+++ b/tools/build/options/WITH_DIRDEPS_BUILD
@@ -1,9 +1,9 @@
 .\" $FreeBSD$
-Enable building in meta mode.
-This is an experimental build feature.
+This is an experimental build system.
 For details see
 http://www.crufty.net/sjg/docs/freebsd-meta-mode.htm.
-.Pp
+Build commands can be seen from the top-level with:
+.Dl make show-valid-targets
 The build is driven by dirdeps.mk using
 .Va DIRDEPS
 stored in
@@ -23,17 +23,13 @@ and child directories.
 .Va NO_DIRDEPS_BELOW
 will skip building any dirdeps and only build the current directory.
 .Pp
-As each target is made
-.Xr make 1
-produces a meta file which is used to capture (and compare)
-the command line,
-as well as any command output.
-If
-.Xr filemon 4
-is available the meta file will also capture a record of files
-used to produce the target by tracking syscalls.
+This also utilizes the
+.Va WITH_META_MODE
+logic for incremental builds.
 .Pp
 The build will hide commands ran unless
 .Va NO_SILENT
 is defined.
 .Pp
+Note that there is currently no mass install feature for this.
+.Pp
diff --git a/tools/build/options/WITH_META_MODE b/tools/build/options/WITH_META_MODE
index 906b557769c9..1d19be1ea4ca 100644
--- a/tools/build/options/WITH_META_MODE
+++ b/tools/build/options/WITH_META_MODE
@@ -1,12 +1,41 @@
 .\" $FreeBSD$
-Create meta files when not doing DIRDEPS_BUILD.
+Creates
+.Xr make 1
+meta files when building, which can provide a reliable incremental build when
+using
+.Xr filemon 4 .
+The meta file is created in the OBJDIR as
+.Pa target.meta .
+These meta files track the command ran, its output, and the current directory.
 When the
 .Xr filemon 4
-module is loaded, dependencies will be tracked for all commands.
-If any command, its dependencies, or files it generates are missing then
-the target will be considered out-of-date and rebuilt.
+module is loaded, any files used by the commands executed will be tracked as
+dependencies for the target in its meta file.
+The target will be considered out-of-date and rebuilt if any of the following
+are true compared to the last build:
+.Bl -bullet -compact
+.It
+The command to execute changes.
+.It
+The current working directory changes.
+.It
+The target's meta file is missing.
+.It
+[requires
+.Xr filemon 4 ]
+Files read, executed or linked to are newer than the target.
+.It
+[requires
+.Xr filemon 4 ]
+Files read, written, executed or linked are missing.
+.El
 The meta files can also be useful for debugging.
 .Pp
 The build will hide commands ran unless
 .Va NO_SILENT
 is defined.
+.Pp
+The build operates as it normally would otherwise.
+This option originally invoked a different build system but that was renamed
+to
+.Va WITH_DIRDEPS_BUILD .