Merge topic 'cleanup-build-commands'

4cce44b Help: Document the CMAKE_MAKE_PROGRAM variable in more detail
558c74d VS: Switch to internal CMAKE_MAKE_PROGRAM lookup by generators
5229f2d Tests: Do not use an explicit make program for VS generators
72dd738 Tests: Fix MFC test heuristic for empty CMAKE_TEST_MAKEPROGRAM
fd6076d Tests: Pass CMAKE_MAKE_PROGRAM instead of --build-makeprogram
68031ab Tests: Configure SubProject-Stage2 test more robustly
003d10c Tests: Simplify VSExcludeFromDefaultBuild configuration
e47d934 Tests: Simplify VSProjectInSubdir configuration
e965cb1 Tests: Simplify CTest.BuildCommand.ProjectInSubdir configuration
72bf255 Tests: Pass --build-options to every test
4d1d772 ctest: Teach --build-options to allow zero options
96966b5 ctest: Make the --build-makeprogram optional for --build-and-test
91a0211 Simplify some calls to cmGlobalGenerator::Build
123a060 Teach GenerateBuildCommand to find its own make program
5f5c92b VS: Add internal APIs to find MSBuild, devenv/VCExpress, and msdev
4ac75fd Prefer CMAKE_MAKE_PROGRAM over CMAKE_BUILD_TOOL (#14548)
...

4 files changed, 79 insertions, 33 deletions

diff --git a/Help/command/build_command.rst b/Help/command/build_command.rst
index f4a56f0..82a9a42 100644
--- a/Help/command/build_command.rst
+++ b/Help/command/build_command.rst
@@ -1,37 +1,44 @@
 build_command
 -------------
 
-Get the command line to build this project.
+Get a command line to build the current project.
+This is mainly intended for internal use by the :module:`CTest` module.
 
-::
+.. code-block:: cmake
 
   build_command(<variable>
                 [CONFIGURATION <config>]
-                [PROJECT_NAME <projname>]
-                [TARGET <target>])
+                [TARGET <target>]
+                [PROJECT_NAME <projname>] # legacy, causes warning
+               )
 
-Sets the given <variable> to a string containing the command line for
-building one configuration of a target in a project using the build
-tool appropriate for the current CMAKE_GENERATOR.
+Sets the given ``<variable>`` to a command-line string of the form::
 
-If CONFIGURATION is omitted, CMake chooses a reasonable default value
-for multi-configuration generators.  CONFIGURATION is ignored for
-single-configuration generators.
+ <cmake> --build . [--config <config>] [--target <target>] [-- -i]
 
-If PROJECT_NAME is omitted, the resulting command line will build the
-top level PROJECT in the current build tree.
+where ``<cmake>`` is the location of the :manual:`cmake(1)` command-line
+tool, and ``<config>`` and ``<target>`` are the values provided to the
+``CONFIGURATION`` and ``TARGET`` options, if any.  The trailing ``-- -i``
+option is added for Makefile generators.
 
-If TARGET is omitted, the resulting command line will build
-everything, effectively using build target 'all' or 'ALL_BUILD'.
+When invoked, this ``cmake --build`` command line will launch the
+underlying build system tool.
 
-::
+.. code-block:: cmake
 
   build_command(<cachevariable> <makecommand>)
 
 This second signature is deprecated, but still available for backwards
 compatibility.  Use the first signature instead.
 
-Sets the given <cachevariable> to a string containing the command to
-build this project from the root of the build tree using the build
-tool given by <makecommand>.  <makecommand> should be the full path to
-msdev, devenv, nmake, make or one of the end user build tools.
+It sets the given ``<cachevariable>`` to a command-line string as
+above but without the ``--config`` or ``--target`` options.
+The ``<makecommand>`` is ignored but should be the full path to
+msdev, devenv, nmake, make or one of the end user build tools
+for legacy invocations.
+
+.. note::
+ In CMake versions prior to 3.0 this command returned a command
+ line that directly invokes the native build tool for the current
+ generator.  Their implementation of the ``PROJECT_NAME`` option
+ had no useful effects, so CMake now warns on use of the option.
diff --git a/Help/manual/ctest.1.rst b/Help/manual/ctest.1.rst
index eee12fd..60d08dd 100644
--- a/Help/manual/ctest.1.rst
+++ b/Help/manual/ctest.1.rst
@@ -225,8 +225,8 @@ Options
  and or execute a test.  The configure and test steps are optional.
  The arguments to this command line are the source and binary
  directories.  By default this will run CMake on the Source/Bin
- directories specified unless --build-nocmake is specified.  Both
- --build-makeprogram and --build-generator MUST be provided to use
+ directories specified unless --build-nocmake is specified.
+ The --build-generator option *must* be provided to use
  --build-and-test.  If --test-command is specified then that will be
  run after the build is complete.  Other options that affect this
  mode are --build-target --build-nocmake, --build-run-dir,
@@ -265,7 +265,7 @@ Options
  Specify the name of the project to build.
 
 ``--build-makeprogram``
- Specify the make program to use.
+ Override the make program chosen by CTest with a given one.
 
 ``--build-noclean``
  Skip the make clean step.
diff --git a/Help/variable/CMAKE_BUILD_TOOL.rst b/Help/variable/CMAKE_BUILD_TOOL.rst
index f0bc938..6133491 100644
--- a/Help/variable/CMAKE_BUILD_TOOL.rst
+++ b/Help/variable/CMAKE_BUILD_TOOL.rst
@@ -1,11 +1,6 @@
 CMAKE_BUILD_TOOL
 ----------------
 
-Tool used for the actual build process.
-
-This variable is set to the program that will be needed to build the
-output of CMake.  If the generator selected was Visual Studio 6, the
-CMAKE_BUILD_TOOL will be set to msdev, for Unix Makefiles it will be
-set to make or gmake, and for Visual Studio 7 it set to devenv.  For
-NMake Makefiles the value is nmake.  This can be useful for adding
-special flags and commands based on the final build environment.
+This variable exists only for backwards compatibility.
+It contains the same value as :variable:`CMAKE_MAKE_PROGRAM`.
+Use that variable instead.
diff --git a/Help/variable/CMAKE_MAKE_PROGRAM.rst b/Help/variable/CMAKE_MAKE_PROGRAM.rst
index 8307bc6..0c851ad 100644
--- a/Help/variable/CMAKE_MAKE_PROGRAM.rst
+++ b/Help/variable/CMAKE_MAKE_PROGRAM.rst
@@ -1,7 +1,51 @@
 CMAKE_MAKE_PROGRAM
 ------------------
 
-See CMAKE_BUILD_TOOL.
+Tool that can launch the native build system.
+The value may be the full path to an executable or just the tool
+name if it is expected to be in the ``PATH``.
 
-This variable is around for backwards compatibility, see
-CMAKE_BUILD_TOOL.
+The tool selected depends on the :variable:`CMAKE_GENERATOR` used
+to configure the project:
+
+* The Makefile generators set this to ``make``, ``gmake``, or
+  a generator-specific tool (e.g. ``nmake`` for "NMake Makefiles").
+
+  These generators store ``CMAKE_MAKE_PROGRAM`` in the CMake cache
+  so that it may be edited by the user.
+
+* The Ninja generator sets this to ``ninja``.
+
+  This generator stores ``CMAKE_MAKE_PROGRAM`` in the CMake cache
+  so that it may be edited by the user.
+
+* The Xcode generator sets this to ``xcodebuild`` (or possibly an
+  otherwise undocumented ``cmakexbuild`` wrapper implementing some
+  workarounds).
+
+  This generator stores ``CMAKE_MAKE_PROGRAM`` in the CMake cache
+  so that it may be edited by the user.
+
+* The Visual Studio generators set this to the full path to
+  ``MSBuild.exe`` (VS >= 10), ``devenv.com`` (VS 7,8,9),
+  ``VCExpress.exe`` (VS Express 8,9), or ``msdev.exe`` (VS 6).
+
+  These generators prefer to lookup the build tool at build time
+  rather than to store ``CMAKE_MAKE_PROGRAM`` in the CMake cache
+  ahead of time.  This is because the tools are version-specific
+  and can be located using the Windows Registry.  It is also
+  necessary because the proper build tool may depend on the
+  project content (e.g. the Intel Fortran plugin to VS 10 and 11
+  requires ``devenv.com`` to build its ``.vfproj`` project files
+  even though ``MSBuild.exe`` is normally preferred to support
+  the :variable:`CMAKE_GENERATOR_TOOLSET`).
+
+  For compatibility with versions of CMake prior to 3.0, if
+  a user or project explicitly adds ``CMAKE_MAKE_PROGRAM`` to
+  the CMake cache then CMake will use the specified value if
+  possible.
+
+The ``CMAKE_MAKE_PROGRAM`` variable is set for use by project code.
+The value is also used by the :manual:`cmake(1)` ``--build`` and
+:manual:`ctest(1)` ``--build-and-test`` tools to launch the native
+build process.