VS: Add option to choose the `.sln` startup project (#15578)

Add a `VS_STARTUP_PROJECT` directory property to specify the project
that should be placed first in the `.sln` file so that it will be
selected as the default startup project.

Co-Author: Taylor Braun-Jones <taylor.braunjones@avigilon.com>

13 files changed, 80 insertions, 1 deletions

diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index fbde4eb..dadbc6e 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -76,6 +76,7 @@ Properties on Directories
    /prop_dir/VARIABLES
    /prop_dir/VS_GLOBAL_SECTION_POST_section
    /prop_dir/VS_GLOBAL_SECTION_PRE_section
+   /prop_dir/VS_STARTUP_PROJECT
 
 .. _`Target Properties`:
 
diff --git a/Help/prop_dir/VS_STARTUP_PROJECT.rst b/Help/prop_dir/VS_STARTUP_PROJECT.rst
new file mode 100644
index 0000000..edd4832
--- /dev/null
+++ b/Help/prop_dir/VS_STARTUP_PROJECT.rst
@@ -0,0 +1,12 @@
+VS_STARTUP_PROJECT
+------------------
+
+Specify the default startup project in a Visual Studio solution.
+
+The property must be set to the name of an existing target.  This
+will cause that project to be listed first in the generated solution
+file causing Visual Studio to make it the startup project if the
+solution has never been opened before.
+
+If this property is not specified, then the "ALL_BUILD" project
+will be the default.
diff --git a/Help/release/dev/vs-startup-project.rst b/Help/release/dev/vs-startup-project.rst
new file mode 100644
index 0000000..f467400
--- /dev/null
+++ b/Help/release/dev/vs-startup-project.rst
@@ -0,0 +1,6 @@
+vs-startup-project
+------------------
+
+* The :ref:`Visual Studio Generators` learned to honor a new
+  :prop_dir:`VS_STARTUP_PROJECT` directory property that specifies
+  the default startup project for generated solutions (``.sln`` files).
diff --git a/Source/cmGlobalVisualStudio71Generator.cxx b/Source/cmGlobalVisualStudio71Generator.cxx
index 8227b82..f6796a5 100644
--- a/Source/cmGlobalVisualStudio71Generator.cxx
+++ b/Source/cmGlobalVisualStudio71Generator.cxx
@@ -94,7 +94,8 @@ void cmGlobalVisualStudio71Generator
   TargetDependSet projectTargets;
   TargetDependSet originalTargets;
   this->GetTargetSets(projectTargets, originalTargets, root, generators);
-  OrderedTargetDependSet orderedProjectTargets(projectTargets, "ALL_BUILD");
+  OrderedTargetDependSet orderedProjectTargets(
+    projectTargets, this->GetStartupProjectName(root));
 
   this->WriteTargetsToSolution(fout, root, orderedProjectTargets);
 
diff --git a/Source/cmGlobalVisualStudioGenerator.cxx b/Source/cmGlobalVisualStudioGenerator.cxx
index 00bb511..b11b49a 100644
--- a/Source/cmGlobalVisualStudioGenerator.cxx
+++ b/Source/cmGlobalVisualStudioGenerator.cxx
@@ -519,6 +519,32 @@ cmGlobalVisualStudioGenerator::GetUtilityDepend(
 }
 
 //----------------------------------------------------------------------------
+std::string
+cmGlobalVisualStudioGenerator::GetStartupProjectName(
+  cmLocalGenerator const* root) const
+{
+  const char* n = root->GetMakefile()->GetProperty("VS_STARTUP_PROJECT");
+  if (n && *n)
+    {
+    std::string startup = n;
+    if (this->FindTarget(startup))
+      {
+      return startup;
+      }
+    else
+      {
+      root->GetMakefile()->IssueMessage(
+        cmake::AUTHOR_WARNING,
+        "Directory property VS_STARTUP_PROJECT specifies target "
+        "'" + startup + "' that does not exist.  Ignoring.");
+      }
+    }
+
+  // default, if not specified
+  return this->GetAllTargetName();
+}
+
+//----------------------------------------------------------------------------
 #include <windows.h>
 
 //----------------------------------------------------------------------------
diff --git a/Source/cmGlobalVisualStudioGenerator.h b/Source/cmGlobalVisualStudioGenerator.h
index ac9111e..723a75f 100644
--- a/Source/cmGlobalVisualStudioGenerator.h
+++ b/Source/cmGlobalVisualStudioGenerator.h
@@ -106,6 +106,8 @@ public:
 
   void ComputeTargetObjectDirectory(cmGeneratorTarget* gt) const;
 
+  std::string GetStartupProjectName(cmLocalGenerator const* root) const;
+
   void AddSymbolExportCommand(
     cmGeneratorTarget*, std::vector<cmCustomCommand>& commands,
     std::string const& configName);
diff --git a/Tests/RunCMake/VSSolution/RunCMakeTest.cmake b/Tests/RunCMake/VSSolution/RunCMakeTest.cmake
index 6ae158d..8ae9598 100644
--- a/Tests/RunCMake/VSSolution/RunCMakeTest.cmake
+++ b/Tests/RunCMake/VSSolution/RunCMakeTest.cmake
@@ -8,3 +8,5 @@ run_cmake(MorePost)
 run_cmake(PrePost)
 run_cmake(Override1)
 run_cmake(Override2)
+run_cmake(StartupProject)
+run_cmake(StartupProjectMissing)
diff --git a/Tests/RunCMake/VSSolution/StartupProject-check.cmake b/Tests/RunCMake/VSSolution/StartupProject-check.cmake
new file mode 100644
index 0000000..352bbd5
--- /dev/null
+++ b/Tests/RunCMake/VSSolution/StartupProject-check.cmake
@@ -0,0 +1,4 @@
+getFirstProject(first_project StartupProject)
+if(NOT first_project STREQUAL "TestStartup")
+  error("TestStartup is not the startup project")
+endif()
diff --git a/Tests/RunCMake/VSSolution/StartupProject.cmake b/Tests/RunCMake/VSSolution/StartupProject.cmake
new file mode 100644
index 0000000..7192f3d
--- /dev/null
+++ b/Tests/RunCMake/VSSolution/StartupProject.cmake
@@ -0,0 +1,2 @@
+add_custom_target(TestStartup)
+set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT "TestStartup")
diff --git a/Tests/RunCMake/VSSolution/StartupProjectMissing-check.cmake b/Tests/RunCMake/VSSolution/StartupProjectMissing-check.cmake
new file mode 100644
index 0000000..95fede7
--- /dev/null
+++ b/Tests/RunCMake/VSSolution/StartupProjectMissing-check.cmake
@@ -0,0 +1,4 @@
+getFirstProject(first_project StartupProjectMissing)
+if(NOT first_project STREQUAL "ALL_BUILD")
+  error("ALL_BUILD is not the startup project")
+endif()
diff --git a/Tests/RunCMake/VSSolution/StartupProjectMissing-stderr.txt b/Tests/RunCMake/VSSolution/StartupProjectMissing-stderr.txt
new file mode 100644
index 0000000..da92c6d
--- /dev/null
+++ b/Tests/RunCMake/VSSolution/StartupProjectMissing-stderr.txt
@@ -0,0 +1,4 @@
+^CMake Warning \(dev\) in CMakeLists.txt:
+  Directory property VS_STARTUP_PROJECT specifies target 'DoesNotExist' that
+  does not exist.  Ignoring.
+This warning is for project developers.  Use -Wno-dev to suppress it.$
diff --git a/Tests/RunCMake/VSSolution/StartupProjectMissing.cmake b/Tests/RunCMake/VSSolution/StartupProjectMissing.cmake
new file mode 100644
index 0000000..907a877
--- /dev/null
+++ b/Tests/RunCMake/VSSolution/StartupProjectMissing.cmake
@@ -0,0 +1 @@
+set_property(DIRECTORY PROPERTY VS_STARTUP_PROJECT "DoesNotExist")
diff --git a/Tests/RunCMake/VSSolution/solution_parsing.cmake b/Tests/RunCMake/VSSolution/solution_parsing.cmake
index dd158ef..001b584 100644
--- a/Tests/RunCMake/VSSolution/solution_parsing.cmake
+++ b/Tests/RunCMake/VSSolution/solution_parsing.cmake
@@ -50,6 +50,20 @@ macro(parseGlobalSections arg_out_pre arg_out_post testName)
 endmacro()
 
 
+macro(getFirstProject arg_out_first_project testName)
+  set(${arg_out_first_project} "")
+  set(sln "${RunCMake_TEST_BINARY_DIR}/${testName}.sln")
+  if(NOT EXISTS "${sln}")
+    error("Expected solution file ${sln} does not exist")
+  endif()
+  file(STRINGS "${sln}" project_lines REGEX "^Project\\(")
+  list(GET project_lines 0 first_project)
+  string(REGEX REPLACE ".* = \"" "" first_project "${first_project}")
+  string(REGEX REPLACE "\", .*"  "" first_project "${first_project}")
+  set(${arg_out_first_project} "${first_project}")
+endmacro()
+
+
 macro(testGlobalSection prefix sectionName)
   if(NOT DEFINED ${prefix}_${sectionName})
     error("Section ${sectionName} does not exist")