From beec9dbc53ba090b47c6613f387b9a59816d3b02 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 25 Nov 2013 09:58:52 -0500 Subject: [PATCH] Help: Organize and revise the cmake-generators.7 manual Move "extra" generators to their own section instead of duplicating them for each corresponding main generator. Divide the list of main generators into command-line and IDE sections and sort the names within each section. Document the environment from which each kind of generator may be used. Add a section to each "extra" generator documenting which main generators may be used with it. --- .../CodeBlocks - NMake Makefiles.rst | 11 --- Help/generator/CodeBlocks - Ninja.rst | 11 --- .../generator/CodeBlocks - Unix Makefiles.rst | 11 --- ...s - MinGW Makefiles.rst => CodeBlocks.rst} | 18 +++- .../Eclipse CDT4 - NMake Makefiles.rst | 11 --- Help/generator/Eclipse CDT4 - Ninja.rst | 11 --- .../Eclipse CDT4 - Unix Makefiles.rst | 11 --- ...- MinGW Makefiles.rst => Eclipse CDT4.rst} | 18 +++- Help/generator/KDevelop3 - Unix Makefiles.rst | 13 --- Help/generator/KDevelop3.rst | 12 +++ .../Sublime Text 2 - NMake Makefiles.rst | 11 --- Help/generator/Sublime Text 2 - Ninja.rst | 11 --- .../Sublime Text 2 - Unix Makefiles.rst | 11 --- ...MinGW Makefiles.rst => Sublime Text 2.rst} | 18 +++- Help/manual/cmake-generators.7.rst | 88 +++++++++++++------ 15 files changed, 123 insertions(+), 143 deletions(-) delete mode 100644 Help/generator/CodeBlocks - NMake Makefiles.rst delete mode 100644 Help/generator/CodeBlocks - Ninja.rst delete mode 100644 Help/generator/CodeBlocks - Unix Makefiles.rst rename Help/generator/{CodeBlocks - MinGW Makefiles.rst => CodeBlocks.rst} (52%) delete mode 100644 Help/generator/Eclipse CDT4 - NMake Makefiles.rst delete mode 100644 Help/generator/Eclipse CDT4 - Ninja.rst delete mode 100644 Help/generator/Eclipse CDT4 - Unix Makefiles.rst rename Help/generator/{Eclipse CDT4 - MinGW Makefiles.rst => Eclipse CDT4.rst} (51%) delete mode 100644 Help/generator/KDevelop3 - Unix Makefiles.rst delete mode 100644 Help/generator/Sublime Text 2 - NMake Makefiles.rst delete mode 100644 Help/generator/Sublime Text 2 - Ninja.rst delete mode 100644 Help/generator/Sublime Text 2 - Unix Makefiles.rst rename Help/generator/{Sublime Text 2 - MinGW Makefiles.rst => Sublime Text 2.rst} (51%) diff --git a/Help/generator/CodeBlocks - NMake Makefiles.rst b/Help/generator/CodeBlocks - NMake Makefiles.rst deleted file mode 100644 index c7f944ab9..000000000 --- a/Help/generator/CodeBlocks - NMake Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -CodeBlocks - NMake Makefiles ----------------------------- - -Generates CodeBlocks project files. - -Project files for CodeBlocks will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. Additionally a hierarchy of makefiles is generated -into the build tree. The appropriate make program can build the -project through the default make target. A "make install" target is -also provided. diff --git a/Help/generator/CodeBlocks - Ninja.rst b/Help/generator/CodeBlocks - Ninja.rst deleted file mode 100644 index 0253af608..000000000 --- a/Help/generator/CodeBlocks - Ninja.rst +++ /dev/null @@ -1,11 +0,0 @@ -CodeBlocks - Ninja ------------------- - -Generates CodeBlocks project files. - -Project files for CodeBlocks will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. Additionally a hierarchy of makefiles is generated -into the build tree. The appropriate make program can build the -project through the default make target. A "make install" target is -also provided. diff --git a/Help/generator/CodeBlocks - Unix Makefiles.rst b/Help/generator/CodeBlocks - Unix Makefiles.rst deleted file mode 100644 index 0a2983554..000000000 --- a/Help/generator/CodeBlocks - Unix Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -CodeBlocks - Unix Makefiles ---------------------------- - -Generates CodeBlocks project files. - -Project files for CodeBlocks will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. Additionally a hierarchy of makefiles is generated -into the build tree. The appropriate make program can build the -project through the default make target. A "make install" target is -also provided. diff --git a/Help/generator/CodeBlocks - MinGW Makefiles.rst b/Help/generator/CodeBlocks.rst similarity index 52% rename from Help/generator/CodeBlocks - MinGW Makefiles.rst rename to Help/generator/CodeBlocks.rst index f54eb115f..01798c7f0 100644 --- a/Help/generator/CodeBlocks - MinGW Makefiles.rst +++ b/Help/generator/CodeBlocks.rst @@ -1,5 +1,5 @@ -CodeBlocks - MinGW Makefiles ----------------------------- +CodeBlocks +---------- Generates CodeBlocks project files. @@ -9,3 +9,17 @@ a PROJECT() call. Additionally a hierarchy of makefiles is generated into the build tree. The appropriate make program can build the project through the default make target. A "make install" target is also provided. + +This "extra" generator may be specified as: + +``CodeBlocks - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``CodeBlocks - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``CodeBlocks - Ninja`` + Generate with :generator:`Ninja`. + +``CodeBlocks - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/Eclipse CDT4 - NMake Makefiles.rst b/Help/generator/Eclipse CDT4 - NMake Makefiles.rst deleted file mode 100644 index b5133add5..000000000 --- a/Help/generator/Eclipse CDT4 - NMake Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -Eclipse CDT4 - NMake Makefiles ------------------------------- - -Generates Eclipse CDT 4.0 project files. - -Project files for Eclipse will be created in the top directory. In -out of source builds, a linked resource to the top level source -directory will be created. Additionally a hierarchy of makefiles is -generated into the build tree. The appropriate make program can build -the project through the default make target. A "make install" target -is also provided. diff --git a/Help/generator/Eclipse CDT4 - Ninja.rst b/Help/generator/Eclipse CDT4 - Ninja.rst deleted file mode 100644 index 270011f40..000000000 --- a/Help/generator/Eclipse CDT4 - Ninja.rst +++ /dev/null @@ -1,11 +0,0 @@ -Eclipse CDT4 - Ninja --------------------- - -Generates Eclipse CDT 4.0 project files. - -Project files for Eclipse will be created in the top directory. In -out of source builds, a linked resource to the top level source -directory will be created. Additionally a hierarchy of makefiles is -generated into the build tree. The appropriate make program can build -the project through the default make target. A "make install" target -is also provided. diff --git a/Help/generator/Eclipse CDT4 - Unix Makefiles.rst b/Help/generator/Eclipse CDT4 - Unix Makefiles.rst deleted file mode 100644 index c3449a71a..000000000 --- a/Help/generator/Eclipse CDT4 - Unix Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -Eclipse CDT4 - Unix Makefiles ------------------------------ - -Generates Eclipse CDT 4.0 project files. - -Project files for Eclipse will be created in the top directory. In -out of source builds, a linked resource to the top level source -directory will be created. Additionally a hierarchy of makefiles is -generated into the build tree. The appropriate make program can build -the project through the default make target. A "make install" target -is also provided. diff --git a/Help/generator/Eclipse CDT4 - MinGW Makefiles.rst b/Help/generator/Eclipse CDT4.rst similarity index 51% rename from Help/generator/Eclipse CDT4 - MinGW Makefiles.rst rename to Help/generator/Eclipse CDT4.rst index 9e7a26e52..eb68bf094 100644 --- a/Help/generator/Eclipse CDT4 - MinGW Makefiles.rst +++ b/Help/generator/Eclipse CDT4.rst @@ -1,5 +1,5 @@ -Eclipse CDT4 - MinGW Makefiles ------------------------------- +Eclipse CDT4 +------------ Generates Eclipse CDT 4.0 project files. @@ -9,3 +9,17 @@ directory will be created. Additionally a hierarchy of makefiles is generated into the build tree. The appropriate make program can build the project through the default make target. A "make install" target is also provided. + +This "extra" generator may be specified as: + +``Eclipse CDT4 - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Eclipse CDT4 - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Eclipse CDT4 - Ninja`` + Generate with :generator:`Ninja`. + +``Eclipse CDT4 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/generator/KDevelop3 - Unix Makefiles.rst b/Help/generator/KDevelop3 - Unix Makefiles.rst deleted file mode 100644 index 2a29a2e4e..000000000 --- a/Help/generator/KDevelop3 - Unix Makefiles.rst +++ /dev/null @@ -1,13 +0,0 @@ -KDevelop3 - Unix Makefiles --------------------------- - -Generates KDevelop 3 project files. - -Project files for KDevelop 3 will be created in the top directory and -in every subdirectory which features a CMakeLists.txt file containing -a PROJECT() call. If you change the settings using KDevelop cmake -will try its best to keep your changes when regenerating the project -files. Additionally a hierarchy of UNIX makefiles is generated into -the build tree. Any standard UNIX-style make program can build the -project through the default make target. A "make install" target is -also provided. diff --git a/Help/generator/KDevelop3.rst b/Help/generator/KDevelop3.rst index 788d55703..eaa218bc8 100644 --- a/Help/generator/KDevelop3.rst +++ b/Help/generator/KDevelop3.rst @@ -11,3 +11,15 @@ files. Additionally a hierarchy of UNIX makefiles is generated into the build tree. Any standard UNIX-style make program can build the project through the default make target. A "make install" target is also provided. + +This "extra" generator may be specified as: + +``KDevelop3 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. + +``KDevelop3`` + Generate with :generator:`Unix Makefiles`. + + For historical reasons this extra generator may be specified + directly as the main generator and it will be used as the + extra generator with :generator:`Unix Makefiles` automatically. diff --git a/Help/generator/Sublime Text 2 - NMake Makefiles.rst b/Help/generator/Sublime Text 2 - NMake Makefiles.rst deleted file mode 100644 index 5e02fd474..000000000 --- a/Help/generator/Sublime Text 2 - NMake Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -Sublime Text 2 - NMake Makefiles --------------------------------- - -Generates Sublime Text 2 project files. - -Project files for Sublime Text 2 will be created in the top directory -and in every subdirectory which features a CMakeLists.txt file -containing a PROJECT() call. Additionally Makefiles (or build.ninja -files) are generated into the build tree. The appropriate make -program can build the project through the default make target. A -"make install" target is also provided. diff --git a/Help/generator/Sublime Text 2 - Ninja.rst b/Help/generator/Sublime Text 2 - Ninja.rst deleted file mode 100644 index b7a2b886d..000000000 --- a/Help/generator/Sublime Text 2 - Ninja.rst +++ /dev/null @@ -1,11 +0,0 @@ -Sublime Text 2 - Ninja ----------------------- - -Generates Sublime Text 2 project files. - -Project files for Sublime Text 2 will be created in the top directory -and in every subdirectory which features a CMakeLists.txt file -containing a PROJECT() call. Additionally Makefiles (or build.ninja -files) are generated into the build tree. The appropriate make -program can build the project through the default make target. A -"make install" target is also provided. diff --git a/Help/generator/Sublime Text 2 - Unix Makefiles.rst b/Help/generator/Sublime Text 2 - Unix Makefiles.rst deleted file mode 100644 index 67d329e84..000000000 --- a/Help/generator/Sublime Text 2 - Unix Makefiles.rst +++ /dev/null @@ -1,11 +0,0 @@ -Sublime Text 2 - Unix Makefiles -------------------------------- - -Generates Sublime Text 2 project files. - -Project files for Sublime Text 2 will be created in the top directory -and in every subdirectory which features a CMakeLists.txt file -containing a PROJECT() call. Additionally Makefiles (or build.ninja -files) are generated into the build tree. The appropriate make -program can build the project through the default make target. A -"make install" target is also provided. diff --git a/Help/generator/Sublime Text 2 - MinGW Makefiles.rst b/Help/generator/Sublime Text 2.rst similarity index 51% rename from Help/generator/Sublime Text 2 - MinGW Makefiles.rst rename to Help/generator/Sublime Text 2.rst index 6e2ed02b5..0597a9528 100644 --- a/Help/generator/Sublime Text 2 - MinGW Makefiles.rst +++ b/Help/generator/Sublime Text 2.rst @@ -1,5 +1,5 @@ -Sublime Text 2 - MinGW Makefiles --------------------------------- +Sublime Text 2 +-------------- Generates Sublime Text 2 project files. @@ -9,3 +9,17 @@ containing a PROJECT() call. Additionally Makefiles (or build.ninja files) are generated into the build tree. The appropriate make program can build the project through the default make target. A "make install" target is also provided. + +This "extra" generator may be specified as: + +``Sublime Text 2 - MinGW Makefiles`` + Generate with :generator:`MinGW Makefiles`. + +``Sublime Text 2 - NMake Makefiles`` + Generate with :generator:`NMake Makefiles`. + +``Sublime Text 2 - Ninja`` + Generate with :generator:`Ninja`. + +``Sublime Text 2 - Unix Makefiles`` + Generate with :generator:`Unix Makefiles`. diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst index ec1f58acb..93fbf77dc 100644 --- a/Help/manual/cmake-generators.7.rst +++ b/Help/manual/cmake-generators.7.rst @@ -7,40 +7,78 @@ cmake-generators(7) .. contents:: -All Generators -============== +Introduction +============ + +A *CMake Generator* is responsible for writing the input files for +a native build system. Exactly one of the `CMake Generators`_ must be +selected for a build tree to determine what native build system is to +be used. Optionally one of the `Extra Generators`_ may be selected +as a variant of some of the `Command-Line Build Tool Generators`_ to +produce project files for an auxiliary IDE. + +CMake Generators are platform-specific so each may be available only +on certain platforms. The :manual:`cmake(1)` command-line tool ``--help`` +output lists available generators on the current platform. Use its ``-G`` +option to specify the generator for a new build tree. +The :manual:`cmake-gui(1)` offers interactive selection of a generator +when creating a new build tree. + +CMake Generators +================ + +Command-Line Build Tool Generators +---------------------------------- + +These generators support command-line build tools. In order to use them, +one must launch CMake from a command-line prompt whose environment is +already configured for the chosen compiler and build tool. .. toctree:: :maxdepth: 1 /generator/Borland Makefiles - /generator/CodeBlocks - MinGW Makefiles - /generator/CodeBlocks - Ninja - /generator/CodeBlocks - NMake Makefiles - /generator/CodeBlocks - Unix Makefiles - /generator/Eclipse CDT4 - MinGW Makefiles - /generator/Eclipse CDT4 - Ninja - /generator/Eclipse CDT4 - NMake Makefiles - /generator/Eclipse CDT4 - Unix Makefiles - /generator/KDevelop3 - /generator/KDevelop3 - Unix Makefiles - /generator/MinGW Makefiles /generator/MSYS Makefiles - /generator/Ninja - /generator/NMake Makefiles JOM + /generator/MinGW Makefiles /generator/NMake Makefiles - /generator/Sublime Text 2 - MinGW Makefiles - /generator/Sublime Text 2 - Ninja - /generator/Sublime Text 2 - NMake Makefiles - /generator/Sublime Text 2 - Unix Makefiles + /generator/NMake Makefiles JOM + /generator/Ninja /generator/Unix Makefiles + /generator/Watcom WMake + +IDE Build Tool Generators +------------------------- + +These generators support Integrated Development Environment (IDE) +project files. Since the IDEs configure their own environment +one may launch CMake from any environment. + +.. toctree:: + :maxdepth: 1 + + /generator/Visual Studio 6 + /generator/Visual Studio 7 + /generator/Visual Studio 7 .NET 2003 + /generator/Visual Studio 8 2005 + /generator/Visual Studio 9 2008 /generator/Visual Studio 10 2010 /generator/Visual Studio 11 2012 /generator/Visual Studio 12 2013 - /generator/Visual Studio 6 - /generator/Visual Studio 7 .NET 2003 - /generator/Visual Studio 7 - /generator/Visual Studio 8 2005 - /generator/Visual Studio 9 2008 - /generator/Watcom WMake /generator/Xcode + +Extra Generators +================ + +Some of the `CMake Generators`_ listed in the :manual:`cmake(1)` +command-line tool ``--help`` output may have variants that specify +an extra generator for an auxiliary IDE tool. Such generator +names have the form `` - ``. +The following extra generators are known to CMake. + +.. toctree:: + :maxdepth: 1 + + /generator/CodeBlocks + /generator/Eclipse CDT4 + /generator/KDevelop3 + /generator/Sublime Text 2