Re: make: warn about fallback from parallel to compat mode

Simon J. Gerraty <[email protected]> wrote:
> A reference to a specific sub-section in make(1) would be a good option.
> Eg. something like?
> 
> Errors
>      Some errors or warnings reported by make require explaination.
> 
>      Rather than have make output voluminous descriptions, it can refer to
>      this section of the manual.
> 
>      -J      This is an internal flag passed in the environment variable
>              MAKEFLAGS.  It communicates the file descriptors for accessing
>              the job token pipe.  If in jobs mode, make finds that the
>              descriptors referenced are not valid, it will drop to
>              compatibility mode.
> 
>              Adding the -B option or setting .MAKE.MODE to `compat' lets make
>              know it is supposed to be in compatibility mode and no warning
>              will be issued.

FWIW That would look something like the diff below.
The last option about setting .MAKE.ALWAYS_PASS_JOB_QUEUE is
bmake only - would be removed for NetBSD.

As you can see, this approach allows for a much more elaborate
explaination than make can/should output.

--sjg

diff -r 6ea478c0d9d4 bmake/main.c
--- a/bmake/main.c	Sat May 31 22:07:48 2025 -0700
+++ b/bmake/main.c	Tue Jun 03 15:13:33 2025 -0700
@@ -1218,25 +1218,15 @@
 	int n;
 
 	if (bogusJflag && !opts.compatMake) {
+		size_t prognameLen = strcspn(progname, "[");
+		
 		opts.compatMake = true;
 		Parse_Error(PARSE_WARNING,
 		    "internal option \"-J\" in \"%s\" "
 		    "refers to unopened file descriptors; "
 		    "falling back to compat mode.\n"
-		    "\t"
-		    "To run the target even in -n mode, "
-		    "add the .MAKE pseudo-source to the target.\n"
-		    "\t"
-		    "To run the target in default mode only, "
-		    "add a ${:D make} marker to a target's command. "
-		    "(This marker expression expands to an empty string.)\n"
-		    "\t"
-		    "To make the sub-make run in compat mode, add -B to "
-		    "its invocation."
-		    "To make the sub-make independent from the parent make, "
-		    "unset the MAKEFLAGS environment variable in the "
-		    "target's commands.\n",
-		    curdir);
+		    "\tSee \"-J\" in Errors section of %.*s(1)\n",
+		    curdir, (int)prognameLen, progname);
 		PrintStackTrace(true);
 		return;
 	}
diff -r 6ea478c0d9d4 bmake/make.1
--- a/bmake/make.1	Sat May 31 22:07:48 2025 -0700
+++ b/bmake/make.1	Tue Jun 03 15:13:33 2025 -0700
@@ -2858,3 +2858,53 @@
 Sometimes the attempt to suppress a cascade of unnecessary errors,
 can result in a seemingly unexplained
 .Ql *** Error code 6
+.Sh Errors
+Some errors or warnings reported by
+.Nm
+require explaination.
+.Pp
+Rather than have
+.Nm
+output voluminous descriptions, it can refer to this
+section of the manual.
+.Bl -tag -width Ds
+.It Fl J
+This is an internal flag passed in the environment variable
+.Ev MAKEFLAGS .
+It communicates the file descriptors for accessing the job token
+pipe.
+If in jobs mode,
+.Nm
+finds that the descriptors referenced are not valid,
+it will drop to compatibility mode.
+.Pp
+This warning can be suppressed by letting
+.Nm
+know that it is supposed to be in compatibility mode by;
+adding the
+.Fl B
+option,
+or setting
+.Va .MAKE.MODE
+to
+.Ql compat ,
+or clearing
+.Ev MAKEFLAGS
+in the environment of the sub-make.
+.Pp
+Alternatively, the target can be marked with the pseudo-source
+.Ic .MAKE ,
+or a token such as
+.Ql ${:D make}
+(which will expand to nothing),
+can be added to the target script to indicate that it will
+run
+.Nm ,
+and the desciptors will be passed.
+.Pp
+Finally the variable
+.Va .MAKE.ALWAYS_PASS_JOB_QUEUE
+can be set true.
+.El
+
+
diff -r 6ea478c0d9d4 bmake/unit-tests/opt-jobs-internal.exp
--- a/bmake/unit-tests/opt-jobs-internal.exp	Sat May 31 22:07:48 2025 -0700
+++ b/bmake/unit-tests/opt-jobs-internal.exp	Tue Jun 03 15:13:33 2025 -0700
@@ -1,22 +1,16 @@
 direct: mode=parallel
 make: error: invalid internal option "-J garbage" in "<curdir>"
 make: warning: internal option "-J" in "<curdir>" refers to unopened file descriptors; falling back to compat mode.
-	To run the target even in -n mode, add the .MAKE pseudo-source to the target.
-	To run the target in default mode only, add a ${:D make} marker to a target's command. (This marker expression expands to an empty string.)
-	To make the sub-make run in compat mode, add -B to its invocation.To make the sub-make independent from the parent make, unset the MAKEFLAGS environment variable in the target's commands.
+	See "-J" in Errors section of make(1)
 
 direct-open: mode=compat
 make: warning: internal option "-J" in "<curdir>" refers to unopened file descriptors; falling back to compat mode.
-	To run the target even in -n mode, add the .MAKE pseudo-source to the target.
-	To run the target in default mode only, add a ${:D make} marker to a target's command. (This marker expression expands to an empty string.)
-	To make the sub-make run in compat mode, add -B to its invocation.To make the sub-make independent from the parent make, unset the MAKEFLAGS environment variable in the target's commands.
+	See "-J" in Errors section of make(1)
 
 indirect-open: mode=compat
 indirect-expr: mode=parallel
 make: warning: internal option "-J" in "<curdir>" refers to unopened file descriptors; falling back to compat mode.
-	To run the target even in -n mode, add the .MAKE pseudo-source to the target.
-	To run the target in default mode only, add a ${:D make} marker to a target's command. (This marker expression expands to an empty string.)
-	To make the sub-make run in compat mode, add -B to its invocation.To make the sub-make independent from the parent make, unset the MAKEFLAGS environment variable in the target's commands.
+	See "-J" in Errors section of make(1)
 
 indirect-comment: mode=compat
 indirect-silent-comment: mode=parallel