cmake -H to generate build files for CMake project? - visual-studio-code

Question

I recently observed that the CMake Tools Extension in VS Code runs this command to generate the build file for a project I'm working on:
/usr/bin/cmake --no-warn-unused-cli -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE -DCMAKE_BUILD_TYPE:STRING=Debug -H/home/tirthankar/projects/physicc/Light/Editor -B/home/tirthankar/projects/physicc/Light/build -G Ninja
The part I am confused about is the -H/home/tirthankar/projects/physicc/Light/Editor part. I searched the CMake Docs for this behavior, but all I could find for the -H was this:
CMake Docs saying that -H is for printing the help docs to the terminal
So the question is, what does -H do in CMake? Is it a standard feature? Is it a deprecated feature? Did the CMake Tools Extension make a mistake?
For reference, here is the entire output:
[kit] Successfully loaded 3 kits from /home/tirthankar/.local/share/CMakeTools/cmake-tools-kits.json
[main] Configuring folder: Light
[proc] Executing command: /usr/bin/cmake --no-warn-unused-cli -DCMAKE_EXPORT_COMPILE_COMMANDS:BOOL=TRUE -DCMAKE_BUILD_TYPE:STRING=Debug -H/home/tirthankar/projects/physicc/Light/Editor -B/home/tirthankar/projects/physicc/Light/build -G Ninja
[cmake] Not searching for unused variables given on the command line.
[cmake] -- The C compiler identification is GNU 10.3.0
[cmake] -- The CXX compiler identification is GNU 10.3.0
[cmake] -- Check for working C compiler: /usr/bin/cc
[cmake] -- Check for working C compiler: /usr/bin/cc -- works
[cmake] -- Detecting C compiler ABI info
[cmake] -- Detecting C compiler ABI info - done
[cmake] -- Detecting C compile features
[cmake] -- Detecting C compile features - done
[cmake] -- Check for working CXX compiler: /usr/bin/c++
[cmake] -- Check for working CXX compiler: /usr/bin/c++ -- works
[cmake] -- Detecting CXX compiler ABI info
[cmake] -- Detecting CXX compiler ABI info - done
[cmake] -- Detecting CXX compile features
[cmake] -- Detecting CXX compile features - done
[cmake] -- Found OpenGL: /usr/lib/x86_64-linux-gnu/libOpenGL.so
[cmake] -- Looking for pthread.h
[cmake] -- Looking for pthread.h - found
[cmake] -- Performing Test CMAKE_HAVE_LIBC_PTHREAD
[cmake] -- Performing Test CMAKE_HAVE_LIBC_PTHREAD - Failed
[cmake] -- Looking for pthread_create in pthreads
[cmake] -- Looking for pthread_create in pthreads - not found
[cmake] -- Looking for pthread_create in pthread
[cmake] -- Looking for pthread_create in pthread - found
[cmake] -- Found Threads: TRUE
[cmake] -- Using X11 for window creation
[cmake] -- Found X11: /usr/include
[cmake] -- Looking for XOpenDisplay in /usr/lib/x86_64-linux-gnu/libX11.so;/usr/lib/x86_64-linux-gnu/libXext.so
[cmake] -- Looking for XOpenDisplay in /usr/lib/x86_64-linux-gnu/libX11.so;/usr/lib/x86_64-linux-gnu/libXext.so - found
[cmake] -- Looking for gethostbyname
[cmake] -- Looking for gethostbyname - found
[cmake] -- Looking for connect
[cmake] -- Looking for connect - found
[cmake] -- Looking for remove
[cmake] -- Looking for remove - found
[cmake] -- Looking for shmat
[cmake] -- Looking for shmat - found
[cmake] -- Looking for IceConnectionNumber in ICE
[cmake] -- Looking for IceConnectionNumber in ICE - found
[cmake] -- Build spdlog: 1.8.5
[cmake] -- Build type: Debug
[cmake] -- Configuring done
[cmake] -- Generating done
[cmake] -- Build files have been written to: /home/tirthankar/projects/physicc/Light/build
Edit: I opened an issue on the CMake Tools GitHub page.

Answer 1

The -H option is used for printing the help documentation for CMake.
-H has never been a standard or documented CMake flag for generating a project. You should not use it and you should disregard any "resources" that encourage you to use undocumented flags. If a Visual Studio Code extension is using it, you should open an issue with the authors of the extension.
The documented equivalent is -S, which sets the source directory. By default, it is the current directory. It was introduced in CMake 3.13. See the latest documentation here: https://cmake.org/cmake/help/latest/manual/cmake.1.html#generate-a-project-buildsystem
There might be subtle behavioral differences between -H and -S. Do not use undocumented/internal flags.

Answer 2

-H is indeed the flag for displaying the help docs, as #Alex Reinking, but there is another undocumented meaning.
While looking for good resources for learning CMake, I stumbled across CGold, which also mentions the -H flag as a way to supply the path to the source.
Add -H<path-to-source-tree> to set directory with CMakeLists.txt. This internal option is not documented but widely used by community. There must be no spaces between -H and <path-to-source-tree> (otherwise option will be interpreted as synonym to --help). Always must be used with -B option.
Here are some specific pointers to projects which use (or recommend using) the -H flag to point to the source directory.
In fact, as CGold suggests, there was a patch submitted a long time ago which aimed to actually document the internal -H flag.
However, it should be noted that one of the developers replied with
These are undocumented because they are internal options that
are not meant for public use.
So, we should not use those flags, and stick to the functionally equivalent (as pointed out by #Alex Reinking) -S flag if we need to pass in the source directory.