What does the `-H.` option means for CMake?

Question

This answer to a former question on CMake shows this command line:

cmake -H. -Bbuild -G \"MSYS Makefiles\"

What task does the -H.

Answer 1

As mentioned in the linked answer, it is an undocumented option, but looking at the source code reveals its effect:

In cmake::SetArgs():

if(arg.find("-H",0) == 0)
  {    
  directoriesSet = true;
  std::string path = arg.substr(2);
  path = cmSystemTools::CollapseFullPath(path);
  cmSystemTools::ConvertToUnixSlashes(path);
  this->SetHomeDirectory(path);

The last call, SetHomeDirectory actually sets the source directory for the project. The -B option (also undocumented) in turn sets the binary directory.

If these options are not set, the binary directory will be the current folder where cmake is executed, and the source directory can be given as a positional argument (if not found, the source folder will also be the current working directory).

Answer 2

The Hitchhiker’s Guide to the CMake explains both, the legacy and new in CMake 3.13 options:

• -H

  This internal option is not documented but widely used by community.

  and

  Has been replaced in 3.13 with the official source directory flag of -S.

• -B

  Starting with CMake 3.13, -B is an officially supported flag, can handle spaces correctly and can be used independently of the -S or -H options.