From 4b39cca42e350eac79e71f3a495ef76154a72bdf Mon Sep 17 00:00:00 2001
From: Kp <kp@valhallalegends.com>
Date: Tue, 27 Mar 2018 03:49:34 +0000
Subject: [PATCH] Clarify SConf output when rejecting a header

Commit 265af2b9e52d added an extra test for whether the header could be
preprocessed, but reused the string shown when an empty test program is
compiled.  This can confuse users since the same message is shown twice.
Differentiate the messages.

Fixes: 265af2b9e52dc63aafb0d6875b0a8ffeb3fd7594 ("Extend SConf diagnostics for failed system headers")
---
 SConstruct | 21 +++++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/SConstruct b/SConstruct
index fefb3f5aa..62207b875 100644
--- a/SConstruct
+++ b/SConstruct
@@ -911,14 +911,31 @@ int main(int argc,char**argv){(void)argc;(void)argv;
 		# give the user more help.
 		if self.Link(context, text=include + text, main=main, msg='for usable library %s' % lib, successflags=successflags):
 			return
+		# If linking failed, an error report is inevitable.  Probe
+		# progressively simpler configurations to help the user trace
+		# the problem.
 		Compile = self.Compile
 		if Compile(context, text=include + text, main=main, msg='for usable header %s' % header, testflags=successflags):
+			# If this Compile succeeds, then the test program can be
+			# compiled, but it cannot be linked.  The required library
+			# may be missing or broken.
 			return (0, "Header %s is usable, but library %s is not usable." % (header, lib))
-		if Compile(context, text=include, main='', msg='for parseable header %s' % header, testflags=successflags):
+		if Compile(context, text=include, main='', msg='whether compiler can parse header %s' % header, testflags=successflags):
+			# If this Compile succeeds, then the test program cannot be
+			# compiled, but the header can be used with an empty test
+			# program.  Either the test program is broken or it relies
+			# on the header working differently than the used header
+			# actually works.
 			return (1, "Header %s is parseable, but cannot compile the test program." % header)
 		successflags.setdefault('CXXFLAGS', []).append('-E')
-		if Compile(context, text=include, main='', msg='for parseable header %s' % header, testflags=successflags):
+		if Compile(context, text=include, main='', msg='whether preprocessor can parse header %s' % header, testflags=successflags):
+			# If this Compile succeeds, then the used header cannot be
+			# compiled at all.  The header may have a syntax error or
+			# have unmet dependencies.
 			return (2, "Header %s exists, but cannot compile an empty program." % header)
+		# Finally, if nothing at all succeeded, either the header is
+		# completely missing or it is so badly broken that the
+		# preprocessor refuses to run to completion.
 		return (3, "Header %s is missing or unusable." % header)
 	# Compile and link a program that uses a system library.  On
 	# success, return None.  On failure, abort the SConf run.