Sublime: Exclude build tree from source tree project only optionally

Create a `CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable to control
addition of the build tree to `folder_exclude_patterns` in the
`.sublime-project`.  Change the default of this behavior to OFF.

Closes: #16351

Help/manual/cmake-variables.7.rst

@@ -159,6 +159,7 @@ Variables that Change Behavior
    /variable/CMAKE_PROJECT_PROJECT-NAME_INCLUDE
    /variable/CMAKE_SKIP_INSTALL_ALL_DEPENDENCY
    /variable/CMAKE_STAGING_PREFIX
+   /variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
    /variable/CMAKE_SYSTEM_APPBUNDLE_PATH
    /variable/CMAKE_SYSTEM_FRAMEWORK_PATH
    /variable/CMAKE_SYSTEM_IGNORE_PATH

Help/release/dev/st2-exclude-patterns-variable.rst

@@ -0,0 +1,7 @@
+st2-exclude-patterns-variable
+-----------------------------
+
+* The :generator:`Sublime Text 2` extra generator no longer excludes the
+  build tree from the ``.sublime-project`` when it is inside the source tree.
+  The :variable:`CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE` variable
+  was added to control the behavior explicitly.

Help/variable/CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE.rst

@@ -0,0 +1,7 @@
+CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE
+---------------------------------------
+
+If this variable evaluates to ``ON`` at the end of the top-level
+``CMakeLists.txt`` file, the :generator:`Sublime Text 2` extra generator
+excludes the build tree from the ``.sublime-project`` if it is inside the
+source tree.

Source/cmExtraSublimeTextGenerator.cxx

@@ -55,10 +55,14 @@ cmExtraSublimeTextGenerator::GetFactory()
 cmExtraSublimeTextGenerator::cmExtraSublimeTextGenerator()
   : cmExternalMakefileProjectGenerator()
 {
+  this->ExcludeBuildFolder = false;
 }
 
 void cmExtraSublimeTextGenerator::Generate()
 {
+  this->ExcludeBuildFolder = this->GlobalGenerator->GlobalSettingIsOn(
+    "CMAKE_SUBLIME_TEXT_2_EXCLUDE_BUILD_TREE");
+
   // for each sub project in the project create a sublime text 2 project
   for (std::map<std::string, std::vector<cmLocalGenerator*> >::const_iterator
          it = this->GlobalGenerator->GetProjectMap().begin();
@@ -84,6 +88,7 @@ void cmExtraSublimeTextGenerator::CreateNewProjectFile(
   const std::vector<cmLocalGenerator*>& lgs, const std::string& filename)
 {
   const cmMakefile* mf = lgs[0]->GetMakefile();
+
   cmGeneratedFileStream fout(filename.c_str());
   if (!fout) {
     return;
@@ -102,9 +107,11 @@ void cmExtraSublimeTextGenerator::CreateNewProjectFile(
     if ((!outputRelativeToSourceRoot.empty()) &&
         ((outputRelativeToSourceRoot.length() < 3) ||
          (outputRelativeToSourceRoot.substr(0, 3) != "../"))) {
+      if (this->ExcludeBuildFolder) {
         fout << ",\n\t\t\t\"folder_exclude_patterns\": [\""
              << outputRelativeToSourceRoot << "\"]";
       }
+    }
   } else {
     fout << "\t{\n\t\t\t\"path\": \"./\"";
   }

Source/cmExtraSublimeTextGenerator.h

@@ -64,6 +64,8 @@ private:
 
   std::string ComputeDefines(cmSourceFile* source, cmLocalGenerator* lg,
                              cmGeneratorTarget* gtgt);
+
+  bool ExcludeBuildFolder;
 };
 
 #endif