59

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

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

What task does the -H. option perform here? cmake --help says that -H prints the help...

I am using CMake 3.2.3.

Community
  • 1
  • 1
Eleno
  • 2,864
  • 3
  • 33
  • 39

2 Answers2

63

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).

Akos Bannerth
  • 1,964
  • 18
  • 14
  • 36
    Why are those not documented? :O – grisevg Sep 21 '16 at 10:38
  • 15
    @grisevg There was a patch submitted to [fix the documentation issue](https://cmake.org/pipermail/cmake-developers/2016-June/028843.html). But it was rejected. There is still no satisfying answer as to why this can't either be documented or removed (if there really is a risk). It seems the development team is not supporting these options for public use. – wally Feb 23 '17 at 14:28
  • 7
    I have `cmake version 3.13.4`, where `-H` aliased to `--help` man says `--help,-help,-usage,-h,-H,/? Print usage information and exit.` – kyb May 29 '19 at 08:56
  • 1
    So, then... what's the difference between `-H` and `-S`? -- setting project "Home" seems like it would handle more edge cases than just setting the source location... EDIT: per the answer below, it looks like they are just the same option, and that `-S` is replacing `-H`. -- That's not intuitive at all IMO. But, glad someone pointed it out! – BrainSlugs83 Sep 24 '20 at 22:03
35

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.

mloskot
  • 37,086
  • 11
  • 109
  • 136