Add optional keyword argument auto_filter_projects to MSVSSolution.

Changes:
* Detect solution file names and nodes in projects argument list.  Behavior based on the auto_filter_projects value.  By default, raise an exception.
* Update TestSConsMSVS and multiple project auto_build_solution tests.
* Update documentation, CHANGES.txt, and RELEASE.txt.

2 files changed, 85 insertions, 1 deletions

diff --git a/SCons/Tool/msvs.py b/SCons/Tool/msvs.py
index 9cb28af..b327653 100644
--- a/SCons/Tool/msvs.py
+++ b/SCons/Tool/msvs.py
@@ -1481,6 +1481,7 @@ class _GenerateV10DSP(_DSPGenerator, _GenerateV10User):
         _GenerateV10User.Build(self)
 
 def _projectDSPNodes(env):
+    auto_filter_projects = env.get('auto_filter_projects', None)
     if 'projects' not in env:
         raise SCons.Errors.UserError("You must specify a 'projects' argument to create an MSVSSolution.")
     projects = env['projects']
@@ -1494,7 +1495,22 @@ def _projectDSPNodes(env):
     for p in projects:
         node = env.File(p)
         if os.path.normcase(str(node)).endswith(sln_suffix):
-            continue
+            # solution node detected (possible issues when opening generated solution file with VS IDE)
+            if auto_filter_projects is None:
+                nodestr = str(node)
+                errmsg = (
+                    f"An msvs solution file was detected in the MSVSSolution 'projects' argument: {nodestr!r}.\n"
+                    "  Add MSVSSolution argument 'auto_filter_projects=True' to suppress project solution nodes.\n"
+                    "  Add MSVSSolution argument 'auto_filter_projects=False' to keep project solution nodes.\n"
+                    "  Refer to the MSVSSolution documentation for more information."
+                )
+                raise SCons.Errors.UserError(errmsg)
+            elif auto_filter_projects:
+                # skip solution node
+                continue
+            else:
+                # keep solution node
+                pass
         dspnodes.append(node)
     if len(dspnodes) < 1:
         raise SCons.Errors.UserError("You must specify at least one project node to create an MSVSSolution.")
diff --git a/SCons/Tool/msvs.xml b/SCons/Tool/msvs.xml
index cc4220c..ad3a756 100644
--- a/SCons/Tool/msvs.xml
+++ b/SCons/Tool/msvs.xml
@@ -540,6 +540,74 @@ env.MSVSProject(
           </listitem>
         </varlistentry>
       </variablelist>
+      <para>
+        In addition to the mandatory arguments above, the following optional
+        values may be specified as keyword arguments:
+      </para>
+      <variablelist>
+        <varlistentry>
+          <term><parameter>auto_filter_projects</parameter></term>
+          <listitem>
+            <para>
+              Under certain circumstances, solution file names or
+              solution file nodes may be present in the
+              <parameter>projects</parameter> argument list.
+              When solution file names or nodes are present in the 
+              <parameter>projects</parameter> argument list, the generated
+              solution file may contain erroneous Project records resulting
+              in VS IDE error messages when opening the generated solution
+              file.
+              By default, an exception is raised when a solution file
+              name or solution file node is detected in the
+              <parameter>projects</parameter> argument list.
+            </para>
+            <para>
+              The accepted values for <parameter>auto_filter_projects</parameter>
+              are:
+            </para>
+            <variablelist>
+              <varlistentry>
+                <term><parameter>None</parameter></term>
+                <listitem>
+                  <para>
+                    An exception is raised when a solution file name or solution
+                    file node is detected in the <parameter>projects</parameter>
+                    argument list.
+                  </para>
+                  <para>
+                    <parameter>None</parameter> is the default value.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><parameter>True or evaluates True</parameter></term>
+                <listitem>
+                  <para>
+                    Automatically remove solution file names and solution file
+                    nodes from the <parameter>projects</parameter> argument list.
+                  </para>
+                </listitem>
+              </varlistentry>
+              <varlistentry>
+                <term><parameter>False or evaluates False</parameter></term>
+                <listitem>
+                  <para>
+                    Leave the solution file names and solution file nodes
+                    in the <parameter>projects</parameter> argument list.
+                    An exception is not raised.
+                  </para>
+                  <para>
+                    When opening the generated solution file with the VS IDE,
+                    the VS IDE will likely report that there are erroneous
+                    Project records that are not supported or that need to be
+                    modified.
+                  </para>
+                </listitem>
+              </varlistentry>
+            </variablelist>
+          </listitem>
+        </varlistentry>
+      </variablelist>
       <para>Example Usage:</para>
       <example_commands>
 env.MSVSSolution(