Issue
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.
Solution
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.
Answered By - Alex Reinking