cmake: -S and -B can be used to specify source and build directories

Document the previously internal option of '-B' and provide a
matching source directory option with '-S'. Both '-B', and '-S'
can be used independently of each other.

Help/manual/OPTIONS_BUILD.txt

@@ -1,3 +1,11 @@
+``-S <path-to-source>``
+ Path to root directory of the CMake project to build.
+
+``-B <path-to-build>``
+ Path to directory which CMake will use as the root of build directory.
+
+ If the directory doesn't already exist CMake will make it.
+
 ``-C <initial-cache>``
  Pre-load a script to populate the cache.
 

Help/manual/cmake.1.rst

@@ -9,6 +9,7 @@ Synopsis
 .. parsed-literal::
 
  cmake [<options>] {<path-to-source> | <path-to-existing-build>}
+ cmake [<options>] -S <path-to-source> -B <path-to-build>
  cmake [{-D <var>=<value>}...] -P <cmake-script-file>
  cmake --build <dir> [<options>...] [-- <build-tool-options>...]
  cmake --open <dir>

Source/cmake.cxx

@@ -611,19 +611,43 @@ void cmake::SetArgs(const std::vector<std::string>& args,
   bool havePlatform = false;
   for (unsigned int i = 1; i < args.size(); ++i) {
     std::string const& arg = args[i];
-    if (arg.find("-H", 0) == 0) {
+    if (arg.find("-H", 0) == 0 || arg.find("-S", 0) == 0) {
       directoriesSet = true;
       std::string path = arg.substr(2);
+      if (path.empty()) {
+        ++i;
+        if (i >= args.size()) {
+          cmSystemTools::Error("No source directory specified for -S");
+          return;
+        }
+        path = args[i];
+        if (path[0] == '-') {
+          cmSystemTools::Error("No source directory specified for -S");
+          return;
+        }
+      }
+
       path = cmSystemTools::CollapseFullPath(path);
       cmSystemTools::ConvertToUnixSlashes(path);
       this->SetHomeDirectory(path);
-    } else if (arg.find("-S", 0) == 0) {
-      // There is no local generate anymore.  Ignore -S option.
     } else if (arg.find("-O", 0) == 0) {
       // There is no local generate anymore.  Ignore -O option.
     } else if (arg.find("-B", 0) == 0) {
       directoriesSet = true;
       std::string path = arg.substr(2);
+      if (path.empty()) {
+        ++i;
+        if (i >= args.size()) {
+          cmSystemTools::Error("No build directory specified for -B");
+          return;
+        }
+        path = args[i];
+        if (path[0] == '-') {
+          cmSystemTools::Error("No build directory specified for -B");
+          return;
+        }
+      }
+
       path = cmSystemTools::CollapseFullPath(path);
       cmSystemTools::ConvertToUnixSlashes(path);
       this->SetHomeOutputDirectory(path);
@@ -835,21 +859,28 @@ void cmake::SetDirectoriesFromFile(const char* arg)
       this->SetHomeOutputDirectory(listPath);
     } else {
       // Source directory given on command line.  Use current working
-      // directory as build tree.
+      // directory as build tree if -B hasn't been given already
+      if (this->GetHomeOutputDirectory().empty()) {
         std::string cwd = cmSystemTools::GetCurrentWorkingDirectory();
         this->SetHomeOutputDirectory(cwd);
       }
+    }
     return;
   }
 
-  // We didn't find a CMakeLists.txt or CMakeCache.txt file from the
+  if (this->GetHomeDirectory().empty()) {
-  // argument.  Assume it is the path to the source tree, and use the
+    // We didn't find a CMakeLists.txt and it wasn't specified
-  // current working directory as the build tree.
+    // with -S. Assume it is the path to the source tree
     std::string full = cmSystemTools::CollapseFullPath(arg);
-  std::string cwd = cmSystemTools::GetCurrentWorkingDirectory();
     this->SetHomeDirectory(full);
+  }
+  if (this->GetHomeOutputDirectory().empty()) {
+    // We didn't find a CMakeCache.txt and it wasn't specified
+    // with -B. Assume the current working directory as the build tree.
+    std::string cwd = cmSystemTools::GetCurrentWorkingDirectory();
     this->SetHomeOutputDirectory(cwd);
   }
+}
 
 // at the end of this CMAKE_ROOT and CMAKE_COMMAND should be added to the
 // cache

Source/cmake.h

@@ -556,6 +556,8 @@ private:
 };
 
 #define CMAKE_STANDARD_OPTIONS_TABLE                                          \
+  { "-S <path-to-source>", "Explicitly specify a source directory." },        \
+    { "-B <path-to-build>", "Explicitly specify a build directory." },        \
     { "-C <initial-cache>", "Pre-load a script to populate the cache." },     \
     { "-D <var>[:<type>]=<value>", "Create or update a cmake cache entry." }, \
     { "-U <globbing_expr>", "Remove matching entries from CMake cache." },    \

Source/cmakemain.cxx

@@ -38,7 +38,8 @@ static const char* cmDocumentationName[][2] = {
 static const char* cmDocumentationUsage[][2] = {
   { nullptr,
     "  cmake [options] <path-to-source>\n"
-    "  cmake [options] <path-to-existing-build>" },
+    "  cmake [options] <path-to-existing-build>\n"
+    "  cmake [options] -S <path-to-source> -B <path-to-build>" },
   { nullptr,
     "Specify a source directory to (re-)generate a build system for "
     "it in the current working directory.  Specify an existing build "

Tests/RunCMake/CommandLine/B-no-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CommandLine/B-no-arg-stderr.txt

@@ -0,0 +1 @@
+CMake Error: No build directory specified for -B

Tests/RunCMake/CommandLine/B-no-arg2-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CommandLine/B-no-arg2-stderr.txt

@@ -0,0 +1 @@
+CMake Error: No build directory specified for -B

Tests/RunCMake/CommandLine/ExplicitDirs/CMakeLists.txt

@@ -0,0 +1,8 @@
+cmake_minimum_required(VERSION 3.0.0 FATAL_ERROR)
+add_custom_command(
+  OUTPUT output.txt
+  COMMAND ${CMAKE_COMMAND} -E echo CustomCommand > output.txt
+  )
+add_custom_target(CustomTarget ALL DEPENDS output.txt)
+add_custom_target(CustomTarget2 ALL DEPENDS output.txt)
+add_custom_target(CustomTarget3 ALL DEPENDS output.txt)

Tests/RunCMake/CommandLine/NoArgs-stdout.txt

@@ -2,6 +2,7 @@
 
   cmake \[options\] <path-to-source>
   cmake \[options\] <path-to-existing-build>
+  cmake \[options\] -S <path-to-source> -B <path-to-build>
 
 Specify a source directory to \(re-\)generate a build system for it in the
 current working directory.  Specify an existing build directory to

Tests/RunCMake/CommandLine/RunCMakeTest.cmake

@@ -48,6 +48,31 @@ run_cmake_command(cache-bad-entry
 run_cmake_command(cache-empty-entry
   ${CMAKE_COMMAND} --build ${RunCMake_SOURCE_DIR}/cache-empty-entry/)
 
+function(run_ExplicitDirs)
+  set(source_dir ${RunCMake_SOURCE_DIR}/ExplicitDirs)
+  set(binary_dir ${RunCMake_BINARY_DIR}/ExplicitDirs-build)
+
+  file(REMOVE_RECURSE "${binary_dir}")
+  file(MAKE_DIRECTORY "${binary_dir}")
+  run_cmake_command(S-arg ${CMAKE_COMMAND} -S ${source_dir} ${binary_dir})
+  run_cmake_command(S-arg-reverse-order ${CMAKE_COMMAND} ${binary_dir} -S${source_dir} )
+  run_cmake_command(S-no-arg ${CMAKE_COMMAND} -S )
+  run_cmake_command(S-no-arg2 ${CMAKE_COMMAND} -S -T)
+  run_cmake_command(S-B ${CMAKE_COMMAND} -S ${source_dir} -B ${binary_dir})
+
+  # make sure that -B can explicitly construct build directories
+  file(REMOVE_RECURSE "${binary_dir}")
+  run_cmake_command(B-arg ${CMAKE_COMMAND} -B ${binary_dir} ${source_dir})
+  file(REMOVE_RECURSE "${binary_dir}")
+  run_cmake_command(B-arg-reverse-order ${CMAKE_COMMAND} ${source_dir} -B${binary_dir})
+  run_cmake_command(B-no-arg ${CMAKE_COMMAND} -B )
+  run_cmake_command(B-no-arg2 ${CMAKE_COMMAND} -B -T)
+  file(REMOVE_RECURSE "${binary_dir}")
+  run_cmake_command(B-S ${CMAKE_COMMAND} -B${binary_dir} -S${source_dir})
+
+endfunction()
+run_ExplicitDirs()
+
 function(run_BuildDir)
   # Use a single build tree for a few tests without cleaning.
   set(RunCMake_TEST_BINARY_DIR ${RunCMake_BINARY_DIR}/BuildDir-build)

Tests/RunCMake/CommandLine/S-no-arg-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CommandLine/S-no-arg-stderr.txt

@@ -0,0 +1 @@
+CMake Error: No source directory specified for -S

Tests/RunCMake/CommandLine/S-no-arg2-result.txt

@@ -0,0 +1 @@
+1

Tests/RunCMake/CommandLine/S-no-arg2-stderr.txt

@@ -0,0 +1 @@
+CMake Error: No source directory specified for -S