Deprecate "extra" generators in favor of cmake-file-api(7)

The "extra" generators were created in CMake's early years to provide
support for users of specific IDEs by directly generating their project
files alongside make or ninja files.  Nowadays the file-api provides a
more generic, maintainable, well-tested, and robust way for IDEs to view
CMake project build trees.  Deprecate the legacy "extra" generators to
encourage the corresponding IDEs to use the file-api.

Fixes: #19090

17 files changed, 75 insertions, 7 deletions

diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst
index 85da715..5c48bc9 100644
--- a/Help/generator/CodeBlocks.rst
+++ b/Help/generator/CodeBlocks.rst
@@ -1,6 +1,12 @@
 CodeBlocks
 ----------
 
+.. deprecated:: 3.27
+
+  Support for :ref:`Extra Generators` is deprecated and will be removed from
+  a future version of CMake.  IDEs may use the :manual:`cmake-file-api(7)`
+  to view CMake-generated project build trees.
+
 Generates CodeBlocks project files.
 
 Project files for CodeBlocks will be created in the top directory and
diff --git a/Help/generator/CodeLite.rst b/Help/generator/CodeLite.rst
index 4f276df..faec9b9 100644
--- a/Help/generator/CodeLite.rst
+++ b/Help/generator/CodeLite.rst
@@ -1,6 +1,12 @@
 CodeLite
 ----------
 
+.. deprecated:: 3.27
+
+  Support for :ref:`Extra Generators` is deprecated and will be removed from
+  a future version of CMake.  IDEs may use the :manual:`cmake-file-api(7)`
+  to view CMake-generated project build trees.
+
 Generates CodeLite project files.
 
 Project files for CodeLite will be created in the top directory and
diff --git a/Help/generator/Eclipse CDT4.rst b/Help/generator/Eclipse CDT4.rst
index 634e2b6..9c1610d 100644
--- a/Help/generator/Eclipse CDT4.rst
+++ b/Help/generator/Eclipse CDT4.rst
@@ -1,6 +1,12 @@
 Eclipse CDT4
 ------------
 
+.. deprecated:: 3.27
+
+  Support for :ref:`Extra Generators` is deprecated and will be removed from
+  a future version of CMake.  IDEs may use the :manual:`cmake-file-api(7)`
+  to view CMake-generated project build trees.
+
 Generates Eclipse CDT 4.0 project files.
 
 Project files for Eclipse will be created in the top directory.  In
diff --git a/Help/generator/Kate.rst b/Help/generator/Kate.rst
index 129bf63..d12723b 100644
--- a/Help/generator/Kate.rst
+++ b/Help/generator/Kate.rst
@@ -1,6 +1,12 @@
 Kate
 ----
 
+.. deprecated:: 3.27
+
+  Support for :ref:`Extra Generators` is deprecated and will be removed from
+  a future version of CMake.  IDEs may use the :manual:`cmake-file-api(7)`
+  to view CMake-generated project build trees.
+
 Generates Kate project files.
 
 A project file for Kate will be created in the top directory in the top level
diff --git a/Help/generator/Sublime Text 2.rst b/Help/generator/Sublime Text 2.rst
index 0a07ea9..a45ab08 100644
--- a/Help/generator/Sublime Text 2.rst
+++ b/Help/generator/Sublime Text 2.rst
@@ -1,6 +1,12 @@
 Sublime Text 2
 --------------
 
+.. deprecated:: 3.27
+
+  Support for :ref:`Extra Generators` is deprecated and will be removed from
+  a future version of CMake.  IDEs may use the :manual:`cmake-file-api(7)`
+  to view CMake-generated project build trees.
+
 Generates Sublime Text 2 project files.
 
 Project files for Sublime Text 2 will be created in the top directory
diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst
index ed5bbbf..9647f0d 100644
--- a/Help/manual/cmake-generators.7.rst
+++ b/Help/manual/cmake-generators.7.rst
@@ -107,6 +107,12 @@ Other Generators
 Extra Generators
 ================
 
+.. deprecated:: 3.27
+
+  Support for "Extra Generators" is deprecated and will be removed from
+  a future version of CMake.  IDEs may use the :manual:`cmake-file-api(7)`
+  to view CMake-generated project build trees.
+
 Some of the `CMake Generators`_ listed in the :manual:`cmake(1)`
 command-line tool :option:`--help <cmake --help>` output may have
 variants that specify an extra generator for an auxiliary IDE tool.
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 76dc883..7deb6c6 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -781,7 +781,7 @@ Available commands are:
       (:option:`-A ... <cmake -A>`).  The value is a list of platforms known to
       be supported.
     ``extraGenerators``
-      A list of strings with all the extra generators compatible with
+      A list of strings with all the :ref:`Extra Generators` compatible with
       the generator.
 
   ``fileApi``
diff --git a/Help/release/dev/deprecate-extra-generators.rst b/Help/release/dev/deprecate-extra-generators.rst
new file mode 100644
index 0000000..ceb2f4e
--- /dev/null
+++ b/Help/release/dev/deprecate-extra-generators.rst
@@ -0,0 +1,5 @@
+deprecate-extra-generators
+--------------------------
+
+* The :ref:`Extra Generators` have been deprecated.  IDEs may use the
+  :manual:`cmake-file-api(7)` to view CMake-generated project build trees.
diff --git a/Help/variable/CMAKE_EDIT_COMMAND.rst b/Help/variable/CMAKE_EDIT_COMMAND.rst
index 2f4ab1f..b21434f 100644
--- a/Help/variable/CMAKE_EDIT_COMMAND.rst
+++ b/Help/variable/CMAKE_EDIT_COMMAND.rst
@@ -2,7 +2,8 @@ CMAKE_EDIT_COMMAND
 ------------------
 
 Full path to :manual:`cmake-gui(1)` or :manual:`ccmake(1)`.  Defined only for
-:ref:`Makefile Generators` when not using an "extra" generator for an IDE.
+:ref:`Makefile Generators` and :ref:`Ninja Generators` when not using any
+:ref:`Extra Generators`.
 
 This is the full path to the CMake executable that can graphically
 edit the cache.  For example, :manual:`cmake-gui(1)` or :manual:`ccmake(1)`.
diff --git a/Help/variable/CMAKE_EXTRA_GENERATOR.rst b/Help/variable/CMAKE_EXTRA_GENERATOR.rst
index 2c92323..0a113a5 100644
--- a/Help/variable/CMAKE_EXTRA_GENERATOR.rst
+++ b/Help/variable/CMAKE_EXTRA_GENERATOR.rst
@@ -1,6 +1,12 @@
 CMAKE_EXTRA_GENERATOR
 ---------------------
 
+.. deprecated:: 3.27
+
+  Support for :ref:`Extra Generators` is deprecated and will be removed from
+  a future version of CMake.  IDEs may use the :manual:`cmake-file-api(7)`
+  to view CMake-generated project build trees.
+
 The extra generator used to build the project.  See
 :manual:`cmake-generators(7)`.
 
diff --git a/Source/cmExtraCodeBlocksGenerator.cxx b/Source/cmExtraCodeBlocksGenerator.cxx
index 988c5c3..e9e2921 100644
--- a/Source/cmExtraCodeBlocksGenerator.cxx
+++ b/Source/cmExtraCodeBlocksGenerator.cxx
@@ -45,7 +45,7 @@ cmExtraCodeBlocksGenerator::GetFactory()
 {
   static cmExternalMakefileProjectGeneratorSimpleFactory<
     cmExtraCodeBlocksGenerator>
-    factory("CodeBlocks", "Generates CodeBlocks project files.");
+    factory("CodeBlocks", "Generates CodeBlocks project files (deprecated).");
 
   if (factory.GetSupportedGlobalGenerators().empty()) {
 #if defined(_WIN32)
diff --git a/Source/cmExtraCodeLiteGenerator.cxx b/Source/cmExtraCodeLiteGenerator.cxx
index 9e8ac5c..7538a7f 100644
--- a/Source/cmExtraCodeLiteGenerator.cxx
+++ b/Source/cmExtraCodeLiteGenerator.cxx
@@ -33,7 +33,7 @@ cmExtraCodeLiteGenerator::GetFactory()
 {
   static cmExternalMakefileProjectGeneratorSimpleFactory<
     cmExtraCodeLiteGenerator>
-    factory("CodeLite", "Generates CodeLite project files.");
+    factory("CodeLite", "Generates CodeLite project files (deprecated).");
 
   if (factory.GetSupportedGlobalGenerators().empty()) {
 #if defined(_WIN32)
diff --git a/Source/cmExtraEclipseCDT4Generator.cxx b/Source/cmExtraEclipseCDT4Generator.cxx
index a07acdc..6201889 100644
--- a/Source/cmExtraEclipseCDT4Generator.cxx
+++ b/Source/cmExtraEclipseCDT4Generator.cxx
@@ -63,7 +63,8 @@ cmExtraEclipseCDT4Generator::GetFactory()
 {
   static cmExternalMakefileProjectGeneratorSimpleFactory<
     cmExtraEclipseCDT4Generator>
-    factory("Eclipse CDT4", "Generates Eclipse CDT 4.0 project files.");
+    factory("Eclipse CDT4",
+            "Generates Eclipse CDT 4.0 project files (deprecated).");
 
   if (factory.GetSupportedGlobalGenerators().empty()) {
 // TODO: Verify if __CYGWIN__ should be checked.
diff --git a/Source/cmExtraKateGenerator.cxx b/Source/cmExtraKateGenerator.cxx
index 0020690..a128a8b 100644
--- a/Source/cmExtraKateGenerator.cxx
+++ b/Source/cmExtraKateGenerator.cxx
@@ -25,7 +25,7 @@ cmExtraKateGenerator::cmExtraKateGenerator() = default;
 cmExternalMakefileProjectGeneratorFactory* cmExtraKateGenerator::GetFactory()
 {
   static cmExternalMakefileProjectGeneratorSimpleFactory<cmExtraKateGenerator>
-    factory("Kate", "Generates Kate project files.");
+    factory("Kate", "Generates Kate project files (deprecated).");
 
   if (factory.GetSupportedGlobalGenerators().empty()) {
 #if defined(_WIN32)
diff --git a/Source/cmExtraSublimeTextGenerator.cxx b/Source/cmExtraSublimeTextGenerator.cxx
index 19e87d5..33901ac 100644
--- a/Source/cmExtraSublimeTextGenerator.cxx
+++ b/Source/cmExtraSublimeTextGenerator.cxx
@@ -43,7 +43,8 @@ cmExtraSublimeTextGenerator::GetFactory()
 {
   static cmExternalMakefileProjectGeneratorSimpleFactory<
     cmExtraSublimeTextGenerator>
-    factory("Sublime Text 2", "Generates Sublime Text 2 project files.");
+    factory("Sublime Text 2",
+            "Generates Sublime Text 2 project files (deprecated).");
 
   if (factory.GetSupportedGlobalGenerators().empty()) {
 #if defined(_WIN32)
diff --git a/Source/cmGlobalGenerator.cxx b/Source/cmGlobalGenerator.cxx
index 492f848..72eed69 100644
--- a/Source/cmGlobalGenerator.cxx
+++ b/Source/cmGlobalGenerator.cxx
@@ -1327,6 +1327,16 @@ void cmGlobalGenerator::Configure()
   this->BinaryDirectories.insert(
     this->CMakeInstance->GetHomeOutputDirectory());
 
+  if (this->ExtraGenerator && !this->CMakeInstance->GetIsInTryCompile()) {
+    this->CMakeInstance->IssueMessage(
+      MessageType::DEPRECATION_WARNING,
+      cmStrCat("Support for \"Extra Generators\" like\n  ",
+               this->ExtraGenerator->GetName(),
+               "\nis deprecated and will be removed from a future version "
+               "of CMake.  IDEs may use the cmake-file-api(7) to view "
+               "CMake-generated project build trees."));
+  }
+
   // now do it
   this->ConfigureDoneCMP0026AndCMP0024 = false;
   dirMf->Configure();
diff --git a/Tests/RunCMake/ExtraGenerators/Simple-stderr.txt b/Tests/RunCMake/ExtraGenerators/Simple-stderr.txt
new file mode 100644
index 0000000..e327a9f
--- /dev/null
+++ b/Tests/RunCMake/ExtraGenerators/Simple-stderr.txt
@@ -0,0 +1,8 @@
+^CMake Deprecation Warning:
+  Support for "Extra Generators" like
+
+    [^
+]+
+
+  is deprecated and will be removed from a future version of CMake\.  IDEs may
+  use the cmake-file-api\(7\) to view CMake-generated project build trees\.