From ef5a4d964ba1743fd7c343f1a6194ff82936d014 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 15 Feb 2023 10:38:45 -0500 Subject: [PATCH] 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 --- Help/generator/CodeBlocks.rst | 6 ++++++ Help/generator/CodeLite.rst | 6 ++++++ Help/generator/Eclipse CDT4.rst | 6 ++++++ Help/generator/Kate.rst | 6 ++++++ Help/generator/Sublime Text 2.rst | 6 ++++++ Help/manual/cmake-generators.7.rst | 6 ++++++ Help/manual/cmake.1.rst | 2 +- Help/release/dev/deprecate-extra-generators.rst | 5 +++++ Help/variable/CMAKE_EDIT_COMMAND.rst | 3 ++- Help/variable/CMAKE_EXTRA_GENERATOR.rst | 6 ++++++ Source/cmExtraCodeBlocksGenerator.cxx | 2 +- Source/cmExtraCodeLiteGenerator.cxx | 2 +- Source/cmExtraEclipseCDT4Generator.cxx | 3 ++- Source/cmExtraKateGenerator.cxx | 2 +- Source/cmExtraSublimeTextGenerator.cxx | 3 ++- Source/cmGlobalGenerator.cxx | 10 ++++++++++ Tests/RunCMake/ExtraGenerators/Simple-stderr.txt | 8 ++++++++ 17 files changed, 75 insertions(+), 7 deletions(-) create mode 100644 Help/release/dev/deprecate-extra-generators.rst create mode 100644 Tests/RunCMake/ExtraGenerators/Simple-stderr.txt diff --git a/Help/generator/CodeBlocks.rst b/Help/generator/CodeBlocks.rst index 85da71543c..5c48bc9d88 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 4f276df718..faec9b9f7a 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 634e2b6ddf..9c1610d617 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 129bf631be..d12723b4f2 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 0a07ea983b..a45ab08252 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 ed5bbbf6cb..9647f0d11d 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 ` 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 76dc883d38..7deb6c624c 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -781,7 +781,7 @@ Available commands are: (:option:`-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 0000000000..ceb2f4e1a8 --- /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 2f4ab1f62a..b21434f7ff 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 2c9232345f..0a113a5ae6 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 988c5c3d55..e9e2921316 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 9e8ac5cf0e..7538a7f469 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 a07acdc9ae..6201889f22 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 0020690060..a128a8b11f 100644 --- a/Source/cmExtraKateGenerator.cxx +++ b/Source/cmExtraKateGenerator.cxx @@ -25,7 +25,7 @@ cmExtraKateGenerator::cmExtraKateGenerator() = default; cmExternalMakefileProjectGeneratorFactory* cmExtraKateGenerator::GetFactory() { static cmExternalMakefileProjectGeneratorSimpleFactory - 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 19e87d52f8..33901ac594 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 492f848a21..72eed69511 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 0000000000..e327a9f3ec --- /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\.