Add FOLDER target property, for IDEs (#3796)

This work was started from a patch by Thomas Schiffer.
Thanks, Thomas!

See the newly added documentation of the FOLDER target
property for details.

Also added global properties, USE_FOLDERS and
PREDEFINED_TARGETS_FOLDER. See new docs here, too.

By default, the FOLDER target property is used to organize
targets into folders in IDEs that have support for such
organization.

This commit adds "solution folder" support to the Visual
Studio generators. Currently works with versions 7 through
10.

Also, use the new FOLDER property in the ExternalProject
test and in the CMake project itself.

9 files changed, 211 insertions, 1 deletions

diff --git a/Source/cmGlobalGenerator.cxx b/Source/cmGlobalGenerator.cxx
index bd26b5f..8e77294 100644
--- a/Source/cmGlobalGenerator.cxx
+++ b/Source/cmGlobalGenerator.cxx
@@ -1837,6 +1837,38 @@ void cmGlobalGenerator::CreateDefaultGlobalTargets(cmTargets* targets)
     }
 }
 
+//----------------------------------------------------------------------------
+const char* cmGlobalGenerator::GetPredefinedTargetsFolder()
+{
+  const char* prop =
+    this->GetCMakeInstance()->GetProperty("PREDEFINED_TARGETS_FOLDER");
+
+  if (prop)
+    {
+    return prop;
+    }
+
+  return "CMakePredefinedTargets";
+}
+
+//----------------------------------------------------------------------------
+bool cmGlobalGenerator::UseFolderProperty()
+{
+  const char* prop = this->GetCMakeInstance()->GetProperty("USE_FOLDERS");
+
+  // If this property is defined, let the setter turn this on or off...
+  //
+  if (prop)
+    {
+    return cmSystemTools::IsOn(prop);
+    }
+
+  // By default, this feature is ON:
+  //
+  return true;
+}
+
+//----------------------------------------------------------------------------
 cmTarget cmGlobalGenerator::CreateGlobalTarget(
   const char* name, const char* message,
   const cmCustomCommandLines* commandLines,
@@ -1866,6 +1898,14 @@ cmTarget cmGlobalGenerator::CreateGlobalTarget(
     {
     target.AddUtility(dit->c_str());
     }
+
+  // Organize in the "predefined targets" folder:
+  //
+  if (this->UseFolderProperty())
+    {
+    target.SetProperty("FOLDER", this->GetPredefinedTargetsFolder());
+    }
+
   return target;
 }
 
diff --git a/Source/cmGlobalGenerator.h b/Source/cmGlobalGenerator.h
index 878be11..554ee0f 100644
--- a/Source/cmGlobalGenerator.h
+++ b/Source/cmGlobalGenerator.h
@@ -320,6 +320,9 @@ protected:
   // All targets in the entire project.
   std::map<cmStdString,cmTarget *> TotalTargets;
 
+  virtual const char* GetPredefinedTargetsFolder();
+  virtual bool UseFolderProperty();
+
 private:
   float FirstTimeProgress;
   // If you add a new map here, make sure it is copied
diff --git a/Source/cmGlobalVisualStudio71Generator.cxx b/Source/cmGlobalVisualStudio71Generator.cxx
index 1191575..897c3a2 100644
--- a/Source/cmGlobalVisualStudio71Generator.cxx
+++ b/Source/cmGlobalVisualStudio71Generator.cxx
@@ -111,6 +111,13 @@ void cmGlobalVisualStudio71Generator
   OrderedTargetDependSet orderedProjectTargets(projectTargets);
 
   this->WriteTargetsToSolution(fout, root, orderedProjectTargets);
+
+  bool useFolderProperty = this->UseFolderProperty();
+  if (useFolderProperty)
+    {
+    this->WriteFolders(fout);
+    }
+
   // Write out the configurations information for the solution
   fout << "Global\n";
   // Write out the configurations for the solution
@@ -120,6 +127,15 @@ void cmGlobalVisualStudio71Generator
   // Write out the configurations for all the targets in the project
   this->WriteTargetConfigurations(fout, root, orderedProjectTargets);
   fout << "\tEndGlobalSection\n";
+
+  if (useFolderProperty)
+    {
+    // Write out project folders
+    fout << "\tGlobalSection(NestedProjects) = preSolution\n";
+    this->WriteFoldersContent(fout);
+    fout << "\tEndGlobalSection\n";
+    }
+
   // Write the footer for the SLN file
   this->WriteSLNFooter(fout);
 }
diff --git a/Source/cmGlobalVisualStudio7Generator.cxx b/Source/cmGlobalVisualStudio7Generator.cxx
index 9631e9a..f455810 100644
--- a/Source/cmGlobalVisualStudio7Generator.cxx
+++ b/Source/cmGlobalVisualStudio7Generator.cxx
@@ -300,6 +300,48 @@ void cmGlobalVisualStudio7Generator::WriteTargetsToSolution(
                             cmLocalGenerator::START_OUTPUT);
         this->WriteProject(fout, vcprojName, dir.c_str(),
                            *target);
+
+        // Create "solution folder" information from FOLDER target property
+        //
+        if (this->UseFolderProperty())
+          {
+          const char *targetFolder = target->GetProperty("FOLDER");
+          if (targetFolder)
+            {
+            std::vector<cmsys::String> tokens =
+              cmSystemTools::SplitString(targetFolder, '/', false);
+
+            std::string cumulativePath = "";
+
+            for(std::vector<cmsys::String>::iterator iter = tokens.begin();
+                iter != tokens.end(); ++iter)
+              {
+              if(!iter->size())
+                {
+                continue;
+                }
+
+              if (cumulativePath.empty())
+                {
+                cumulativePath = *iter;
+                }
+              else
+                {
+                VisualStudioFolders[cumulativePath].insert(
+                  cumulativePath + "/" + *iter);
+
+                cumulativePath = cumulativePath + "/" + *iter;
+                }
+
+              this->CreateGUID(cumulativePath.c_str());
+              }
+
+            if (!cumulativePath.empty())
+              {
+              VisualStudioFolders[cumulativePath].insert(target->GetName());
+              }
+            }
+          }
         }
       }
     }
@@ -327,6 +369,7 @@ void cmGlobalVisualStudio7Generator::WriteTargetDepends(
     }
 }
 
+//----------------------------------------------------------------------------
 // Write a SLN file to the stream
 void cmGlobalVisualStudio7Generator
 ::WriteSLNFile(std::ostream& fout,
@@ -344,6 +387,13 @@ void cmGlobalVisualStudio7Generator
   OrderedTargetDependSet orderedProjectTargets(projectTargets);
 
   this->WriteTargetsToSolution(fout, root, orderedProjectTargets);
+
+  bool useFolderProperty = this->UseFolderProperty();
+  if (useFolderProperty)
+    {
+    this->WriteFolders(fout);
+    }
+
   // Write out the configurations information for the solution
   fout << "Global\n"
        << "\tGlobalSection(SolutionConfiguration) = preSolution\n";
@@ -361,6 +411,14 @@ void cmGlobalVisualStudio7Generator
   this->WriteTargetDepends(fout, orderedProjectTargets);
   fout << "\tEndGlobalSection\n";
 
+  if (useFolderProperty)
+    {
+    // Write out project folders
+    fout << "\tGlobalSection(NestedProjects) = preSolution\n";
+    this->WriteFoldersContent(fout);
+    fout << "\tEndGlobalSection\n";
+    }
+
   // Write out the configurations for all the targets in the project
   fout << "\tGlobalSection(ProjectConfiguration) = postSolution\n";
   this->WriteTargetConfigurations(fout, root, orderedProjectTargets);
@@ -371,6 +429,47 @@ void cmGlobalVisualStudio7Generator
 }
 
 //----------------------------------------------------------------------------
+void cmGlobalVisualStudio7Generator::WriteFolders(std::ostream& fout)
+{
+  std::string guidProjectTypeFolder = "2150E333-8FDC-42A3-9474-1A3956D46DE8";
+  for(std::map<std::string,std::set<std::string> >::iterator iter =
+    VisualStudioFolders.begin(); iter != VisualStudioFolders.end(); ++iter)
+    {
+    std::string fullName = iter->first;
+    std::string guid = this->GetGUID(fullName.c_str());
+    std::string nameOnly = cmSystemTools::GetFilenameName(fullName);
+    cmSystemTools::ReplaceString(fullName, "/", "\\");
+
+    fout << "Project(\"{" <<
+      guidProjectTypeFolder << "}\") = \"" <<
+      nameOnly << "\", \"" <<
+      fullName << "\", \"{" <<
+      guid <<
+      "}\"\nEndProject\n";
+    }
+}
+
+//----------------------------------------------------------------------------
+void cmGlobalVisualStudio7Generator::WriteFoldersContent(std::ostream& fout)
+{
+  for(std::map<std::string,std::set<std::string> >::iterator iter =
+    VisualStudioFolders.begin(); iter != VisualStudioFolders.end(); ++iter)
+    {
+    std::string key(iter->first);
+    std::string guidParent(this->GetGUID(key.c_str()));
+
+    for(std::set<std::string>::iterator it = iter->second.begin();
+        it != iter->second.end(); ++it)
+      {
+      std::string value(*it);
+      std::string guid(this->GetGUID(value.c_str()));
+
+      fout << "\t\t{" << guid << "} = {" << guidParent << "}\n";
+      }
+    }
+}
+
+//----------------------------------------------------------------------------
 std::string
 cmGlobalVisualStudio7Generator::ConvertToSolutionPath(const char* path)
 {
diff --git a/Source/cmGlobalVisualStudio7Generator.h b/Source/cmGlobalVisualStudio7Generator.h
index 85ba244..b2c7141 100644
--- a/Source/cmGlobalVisualStudio7Generator.h
+++ b/Source/cmGlobalVisualStudio7Generator.h
@@ -142,6 +142,10 @@ protected:
   std::vector<std::string> Configurations;
   std::map<cmStdString, cmStdString> GUIDMap;
 
+  virtual void WriteFolders(std::ostream& fout);
+  virtual void WriteFoldersContent(std::ostream& fout);
+  std::map<std::string,std::set<std::string> > VisualStudioFolders;
+
   // Set during OutputSLNFile with the name of the current project.
   // There is one SLN file per project.
   std::string CurrentProject;
diff --git a/Source/cmGlobalVisualStudio8Generator.cxx b/Source/cmGlobalVisualStudio8Generator.cxx
index 6e0f048..7a979f8 100644
--- a/Source/cmGlobalVisualStudio8Generator.cxx
+++ b/Source/cmGlobalVisualStudio8Generator.cxx
@@ -136,6 +136,13 @@ void cmGlobalVisualStudio8Generator::AddCheckTarget()
                           no_working_directory, no_depends,
                           noCommandLines);
 
+  // Organize in the "predefined targets" folder:
+  //
+  if (this->UseFolderProperty())
+    {
+    tgt->SetProperty("FOLDER", this->GetPredefinedTargetsFolder());
+    }
+
   // Create a list of all stamp files for this project.
   std::vector<std::string> stamps;
   std::string stampList = cmake::GetCMakeFilesDirectoryPostSlash();
diff --git a/Source/cmGlobalVisualStudioGenerator.cxx b/Source/cmGlobalVisualStudioGenerator.cxx
index 85b4a71..e8a00bb 100644
--- a/Source/cmGlobalVisualStudioGenerator.cxx
+++ b/Source/cmGlobalVisualStudioGenerator.cxx
@@ -56,6 +56,21 @@ void cmGlobalVisualStudioGenerator::Generate()
         AddUtilityCommand("ALL_BUILD", true, no_working_dir,
                           no_depends, no_commands, false,
                           "Build all projects");
+
+#if 0
+      // Can't activate this code because we want ALL_BUILD
+      // selected as the default "startup project" when first
+      // opened in Visual Studio... And if it's nested in a
+      // folder, then that doesn't happen.
+      //
+      // Organize in the "predefined targets" folder:
+      //
+      if (this->UseFolderProperty())
+        {
+        allBuild->SetProperty("FOLDER", this->GetPredefinedTargetsFolder());
+        }
+#endif
+
       // Now make all targets depend on the ALL_BUILD target
       cmTargets targets;
       for(std::vector<cmLocalGenerator*>::iterator i = gen.begin();
diff --git a/Source/cmTarget.cxx b/Source/cmTarget.cxx
index 45ba358..9611912 100644
--- a/Source/cmTarget.cxx
+++ b/Source/cmTarget.cxx
@@ -854,10 +854,19 @@ void cmTarget::DefineProperties(cmake *cm)
      "set_source_files_properties command.");
 
   cm->DefineProperty
+    ("FOLDER", cmProperty::TARGET,
+     "Set the folder name. Use to organize targets in an IDE.",
+     "Targets with no FOLDER property will appear as top level "
+     "entities in IDEs like Visual Studio. Targets with the same "
+     "FOLDER property value will appear next to each other in a "
+     "folder of that name. To nest folders, use FOLDER values such "
+     "as 'GUI/Dialogs' with '/' characters separating folder levels.");
+
+  cm->DefineProperty
     ("PROJECT_LABEL", cmProperty::TARGET,
      "Change the name of a target in an IDE.",
      "Can be used to change the name of the target in an IDE "
-     "like visual stuido. ");
+     "like Visual Studio. ");
   cm->DefineProperty
     ("VS_KEYWORD", cmProperty::TARGET,
      "Visual Studio project keyword.",
diff --git a/Source/cmake.cxx b/Source/cmake.cxx
index cb20069..37ff7c5 100644
--- a/Source/cmake.cxx
+++ b/Source/cmake.cxx
@@ -3483,6 +3483,23 @@ void cmake::DefineProperties(cmake *cm)
      "the value of this property.  "
      "Non-Makefile generators currently ignore this property.");
 
+  cm->DefineProperty
+    ("USE_FOLDERS", cmProperty::GLOBAL,
+     "Use the FOLDER target property to organize targets into folders.",
+     "If not set, CMake treats this property as ON by default. "
+     "CMake generators that are capable of organizing into a "
+     "hierarchy of folders use the values of the FOLDER target "
+     "property to name those folders. See also the documentation "
+     "for the FOLDER target property.");
+
+  cm->DefineProperty
+    ("PREDEFINED_TARGETS_FOLDER", cmProperty::GLOBAL,
+     "Name of FOLDER for targets that are added automatically by CMake.",
+     "If not set, CMake uses \"CMakePredefinedTargets\" as a default "
+     "value for this property. Targets such as INSTALL, PACKAGE and "
+     "RUN_TESTS will be organized into this FOLDER. See also the "
+     "documentation for the FOLDER target property.");
+
   // ================================================================
   // define variables as well
   // ================================================================